MCP tools

Every tool at a glance#

Three more tools exist only for the in-chat project view. Your client does not call them.

Every tool also accepts intent, an optional sentence of up to 500 characters on the goal of the call. MAIA records it with the call for its own logs. It does not change what the tool does. Leave out names, addresses, and anything private.

maia_guide#

No parameters beyond intent. Returns a short guide written for your client to read before it uses MAIA.

Starting work#

find_county#

Returns each match with its county_fips and name. Only counties your workspace can use are returned. When nothing matches and your workspace can use 20 counties or fewer, it also returns all of them as available, so your client can offer you one.

{ "county_fips": "04013", "name": "Maricopa County, AZ" }

Pass county_fips on as a string. As a number it loses its leading zero.

create_project#

Returns at once with a run report holding the project id and the run id. Follow the run with get_run. The report's fields are on Runs and approvals.

send_message#

Returns at once with a run report. Use it for questions about the data too. MAIA refuses a new request while a run is in progress on the project, so wait for complete first.

Bringing in a file#

The steps, from your side, are on Upload a file. Your client passes a CSV or GeoJSON file to import_rows, and sends a larger file, or another format, to a link from get_upload_link.

import_rows#

Returns the same response as an upload to a link: the project and, for addresses, an import_id to follow with get_import. The rows go through the same import as a file upload.

get_upload_link#

Returns a one-use link and the command that sends the file to it. The link expires after 10 minutes and works only for you. Your client sends the file from its own code environment, not through a tool call. The response to the upload names the project and, for addresses, an import_id to follow with get_import.

get_import#

Returns the import's progress, then the rows matched to parcels and the rows not matched, with the reason for each. If the import failed, it says why. Only an address import needs it: a map layer or a table is in the project when the upload returns.

Following a run#

get_run#

Returns a run report. Its fields are described in Runs and approvals.

respond#

Send choice for a question and decline for an approval. The report says which kind is pending. A call with the wrong one, or with nothing pending, is refused. respond never approves a step. To approve, use [approve_step](/docs/mcp/tools#approve-step).

{ "project_id": "3f6c1a2e-0000-0000-0000-000000000000", "choice": "a" }

{ "project_id": "3f6c1a2e-0000-0000-0000-000000000000", "decline": true, "note": "Too many rows. Offer a smaller run." }

Returns the run report. The run continues.

approve_step#

Lets MAIA run the step it asked approval for. approval_id and summary must match the pending approval exactly. A call that does not match, or with no approval pending, is refused.

{
  "project_id": "3f6c1a2e-0000-0000-0000-000000000000",
  "approval_id": "toolu_01A2B3C4D5E6F7G8",
  "summary": "Enrich 1,200 rows of Owner contacts on Parcels. That is past your 500-row limit per reply. This run uses 1,200 credits, and leaves 3,800."
}

Returns the run report. The run continues.

stop_run#

Returns whether a run was in progress. A stop is not instant. MAIA halts at the next safe point and keeps what it finished. Calling it twice is safe.

Reading projects#

list_projects#

Each project comes with its id, name, status, last update, and a link to it in MAIA.

get_project#

Returns the project's layers, each with its kind, row count, and column names. It also returns the views, and whether a run is in progress. It does not return rows. To read them, open the project link.

Skills and memory#

list_skills#

Without name, each skill comes back with its name, description, scope, and kind. The full instructions come back only for a skill asked for by name.

save_skill#

Saves a personal skill. Workspace skills are edited in MAIA. See Skills.

save_to_maia_memory#

MAIA reads this memory in every project. It is part of your personal knowledge. See Knowledge.

Limits#

• One county per project. create_project takes one county code.
• No tool reads rows directly. To ask about the data, send the question to MAIA's agent with send_message, and open the project link for the full table.