Provides tools for AI-powered GIS workflow automation through QGIS, translating natural-language requests into validated QGIS Processing plans, executing them step-by-step, and reporting results. Enables planning, running, resuming, and diagnosing GIS workflows using approved QGIS Processing algorithms.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@GIS Assistant MCP clip the parcels layer to the city boundary and save it to my workspace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AI-powered GIS workflow automation via the Model Context Protocol (MCP), backed by QGIS.
Translates natural-language requests into validated QGIS Processing plans, executes them step-by-step, and reports results — through MCP tools (Claude Code / any MCP client) or the built-in chat UI inside QGIS.
┌──────────────────┐
Claude Code ──MCP/stdio──▶ │ │
gis-assistant engine ──┤ TCP/NDJSON ──▶ QGIS Plugin
QGIS Chat UI ──HTTP────────▶ │ │
│ └──────────────────┘
├── Claude or OpenAI (plan generation)
└── Local safety validationTwo transport options share the same core engine:
MCP/stdio (gis-assistant): For Claude Code or any MCP client. Runs as a stdio server.
HTTP API (gis-assistant-api): For the QGIS chat dock widget. Runs as a local HTTP server on port 8100 with bearer token auth.
Both transports call the same GISEngine class, which generates plans through a provider's structured-output API, validates them against an algorithm allowlist and path confinement rules, then executes each step by sending commands to the QGIS MCP plugin over a TCP socket.
Related MCP server: QGIS MCP Server
QGIS 3.x with the qgis_mcp plugin by Juan Santos installed and running — this project is a separate MCP server that drives that plugin over its socket protocol; see Acknowledgments
Python 3.10+
uv package manager
ANTHROPIC_API_KEY — Claude is the default provider. (OpenAI is an
optional alternative; see Choosing a provider.)
cd /path/to/gis-assistant-mcp
uv sync # Claude (default)
uv sync --extra openai # ...or add the optional OpenAI providerVariable | Default | Description |
|
|
|
| (required for Claude) | Read by the Anthropic SDK |
| (required for OpenAI) | Read by the OpenAI SDK. Needs the |
| per provider | Overrides the provider default — |
|
| Output directory (all outputs confined here) |
|
| Port for the HTTP API server |
| (auto-generated) | Bearer token for HTTP API auth. If unset, a random token is generated at startup and printed to stdout. |
Claude (claude-opus-5) is the default and needs no extra install. To use OpenAI
instead:
uv sync --extra openai
export GIS_PLANNER_PROVIDER=openai OPENAI_API_KEY=...Both providers go through the same two-method seam in llm.py, so the engine
holds no vendor-specific code and switching changes no behaviour beyond the model.
On token usage. Adaptive thinking is enabled on both Claude call paths. Plan generation genuinely needs it — the model has to reason about CRS and units, choose among 103 allowed algorithms, and chain one step's outputs into the next — but every request then spends reasoning tokens on top of the response, and that applies to error diagnosis too, not just planning.
This server calls the Anthropic API with an ANTHROPIC_API_KEY, billed per
token. A Claude Pro or Max subscription covers Claude apps such as Claude Code and
claude.ai, but not API usage — the two are separate and metered differently.
Measured input for a typical request is ~1,900 tokens (system prompt 1,621 + a six-layer project context). With output and thinking estimated at 1.8–5.8k tokens:
Model | Cost per plan | Plans per $1 |
| $0.05 – $0.15 | 6 – 18 |
| ~$0.03 | ~32 |
| ~$0.02 | ~63 |
To spend less: set GIS_PLANNER_MODEL to a cheaper model, or drop thinking from
AnthropicProvider in src/gis_assistant/llm.py.
Only plan generation needs a model. The execution engine does not, and because the planner is constructed lazily, no key is read unless you call a planning tool:
Needs a key | No key required |
|
|
So an MCP client that is already a model — Claude Code, for instance — can skip
the built-in planner entirely: call gis.list_capabilities to learn the allowed
operations and limits, author the plan JSON itself, then hand it to gis.run_plan.
Safety validation, path confinement, @-reference resolution and the confirm/resume
gate all still apply, because they live in the executor rather than the planner.
The internal planner exists for the QGIS chat dock, which has no model of its own.
The test suite needs no key and makes no network calls at all:
uv sync && uv run pytest -q # 72 passed, 6 skippedAdd to your .mcp.json (e.g. in your workspace root):
{
"mcpServers": {
"gis_assistant": {
"command": "uv",
"args": ["--directory", "/path/to/gis-assistant-mcp", "run", "gis-assistant"],
"env": {
"GIS_WORKSPACE": "/path/to/your/workspace"
}
}
}
}No MCP client needed. Start the HTTP API and use the chat dock widget inside QGIS:
Start the QGIS MCP plugin socket server (Plugins > QGIS MCP > Start Server)
Open the chat dock: Plugins > QGIS MCP > GIS Assistant Chat
Click Start Engine — this launches the HTTP API as a subprocess and auto-connects
Type your GIS request in the chat input
Alternatively, start the API manually:
cd /path/to/gis-assistant-mcp
uv run gis-assistant-api
# Prints: GIS_API_TOKEN=<token>Then paste the token into the chat dock's token field and click Connect.
Tool | Description |
| Generate a workflow plan from a natural-language prompt (no execution) |
| Resolve clarification questions from a previous |
| Plan and execute a workflow end-to-end |
| Execute a specific plan JSON (for plan → review → edit → execute workflows) |
| Resume a blocked execution after a confirmation step |
| Diagnose a GIS/QGIS error and suggest fixes |
| Show details of the last plan and execution results |
| List supported operations, algorithms, and workspace policy |
When running gis-assistant-api, the following REST endpoints are available on http://127.0.0.1:8100. All endpoints (except /health) require Authorization: Bearer <token>.
Method | Path | Body | Description |
GET |
| - | Health check (no auth) |
GET |
| - | Check if QGIS socket is reachable |
POST |
|
| Generate a workflow plan |
POST |
|
| Resolve clarification questions |
POST |
|
| Plan and execute end-to-end |
POST |
|
| Execute a specific plan dict |
POST |
|
| Resume after confirmation |
POST |
|
| Diagnose an error |
GET |
| query: | List supported algorithms |
GET |
| - | Show last plan/report |
Error responses use a consistent envelope: {"status": "error", "message": "...", "details": {...}}.
No execute_code: Arbitrary Python execution is intentionally excluded.
Algorithm allowlist: Only approved native: and gdal: processing algorithms can run (103 algorithms).
Path confinement: All output paths are resolved and validated to stay within the workspace directory.
Confirmation steps: Plans include confirm steps before overwriting existing files, which halt execution until approved via gis.resume.
Plan size limits: Maximum 20 steps per plan.
Main-thread processing: The QGIS plugin executes processing algorithms on the main thread. Large raster operations (warps, merges, hillshades on multi-GB data) will freeze the QGIS UI. Keep operations scoped to smaller datasets, or run heavy jobs directly from the QGIS Processing Toolbox.
To create a clean distribution zip (excludes __pycache__, .venv, .git, caches):
./scripts/build_dist.shThis produces dist/gis-assistant-mcp.zip including uv.lock for reproducible installs. Without uv.lock, uv sync resolves latest allowed versions which may drift.
uv sync --group dev # install test dependencies
uv run pytest tests/ -vThe QGIS socket client in this project is adapted from qgis_mcp by Juan Santos, which is itself based on BlenderMCP by Siddharth Ahuja.
This is not a fork of qgis_mcp. It is a separate MCP server that drives the qgis_mcp QGIS plugin across that plugin's socket protocol — 12 of qgis_client.py's 113 substantive lines coincide with upstream, all of them send_command names fixed by the wire protocol. See NOTICE for the retained copyright notices and ARCHITECTURE.md for a capability comparison.
MIT License. See LICENSE; third-party copyright notices are retained in NOTICE.
Resolve clarification questions from a previous gis.plan call.
Takes a JSON string of {question_id: answer_value} and re-plans with
the answers merged into the original context. Returns an updated plan.
| Name | Required | Description | Default |
|---|---|---|---|
| answers_json | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that answers are merged into the original context and an updated plan is returned, but it omits side effects, error behavior, and what happens to unanswered questions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and then the parameter format. Every sentence adds value without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. The purpose, input format, and relationship to gis.plan are covered, but the lack of behavioral detail around error cases or incomplete answers leaves a minor gap for an unannotated tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the single parameter as a JSON string mapping question IDs to answer values, which adds significant meaning beyond the bare schema, though it doesn't specify constraints such as whether all questions must be answered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it resolves clarification questions from a previous gis.plan call and re-plans with merged answers. This distinguishes it clearly from gis.plan and other siblings without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear condition for use: after a gis.plan call produces clarification questions. However, it does not explicitly mention when not to use it or name alternative tools like gis.resume, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnose a GIS/QGIS error and suggest fixes.
Provide the error message or traceback. Returns an explanation with likely cause, affected step, and proposed fixes.
| Name | Required | Description | Default |
|---|---|---|---|
| error_text | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that the tool returns an explanation with likely cause, affected step, and proposed fixes, but it does not state whether the tool is read-only, whether it executes anything, or what permissions or limits apply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three front-loaded sentences with no waste: it states purpose, input, and output in order. Every sentence contributes directly to using the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one required parameter, no nested objects, and an output schema exists. The description covers purpose, input source, and return content adequately, though it lacks sibling routing and explicit safety context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single parameter. It does so by specifying that error_text should be the error message or traceback, which adds meaningful semantics beyond the schema title 'Error Text.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Diagnose a GIS/QGIS error and suggest fixes.' It is clear what the tool does, but it does not explicitly distinguish itself from related siblings such as gis.explain_last_run or gis.run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent to 'Provide the error message or traceback,' which is a clear input usage instruction. However, it does not state when to use this tool versus alternatives like gis.explain_last_run, nor does it give exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show details of the last plan and/or execution run.
Returns the plan (inputs, outputs, assumptions, steps) and execution results if gis.run was used.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return contents (inputs, outputs, assumptions, steps, and execution results under a condition), which is helpful. However, it does not clarify whether 'last' refers to the most recent plan or execution run, what happens if no prior run exists, or whether the operation is strictly read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loads the core purpose, and adds conditional return detail without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero-parameter interface, output schema, and low complexity, the description is largely complete for invoking the tool. It explains the returned plan and conditional execution results. Minor gaps include the lack of error/no-prior-run behavior and the ambiguity of 'last' between plan and run.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to document. The baseline score for zero params is 4, and the description appropriately avoids unnecessary parameter discussion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: showing details of the last plan and/or execution run. It clearly identifies the tool's purpose and distinguishes it from siblings like gis.plan and gis.run by focusing on the most recent plan/execution. However, it does not explicitly differentiate itself from gis.diagnose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to inspect the last plan/execution) and mentions that execution results appear only if gis.run was used. It does not provide explicit guidance on when to choose this over alternatives like gis.diagnose or gis.plan, nor does it state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported operations, algorithm categories, and workspace policy.
Args:
verbose: If False (default), show categories with top examples.
If True, list all supported algorithm IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| verbose | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. 'List' implies a safe read-only operation, and the verbose flag's effect on output volume is disclosed, but nothing is said about cost, latency, caching, or whether workspace policy reflects the caller's permissions. Adequate but thin for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose sentence followed by a compact Args block that documents the single parameter. Every line earns its place; the only minor waste is formatting the docstring convention rather than prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, leaving purpose and the one parameter as the real burden — both are covered. The remaining gap is routing guidance relative to the six sibling tools, which matters given how many alternatives exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does: it explains both states of verbose — categories with top examples by default versus all algorithm IDs when true. This is meaningful behavior-level detail the bare boolean schema does not convey. It stops short of defining what a 'category' or 'top example' is.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A specific verb-plus-resource statement: 'List supported operations, algorithm categories, and workspace policy' tells the agent exactly what content comes back. It does not explicitly distinguish itself from siblings like gis.plan or gis.run, but the discovery nature of the tool is unambiguous from the wording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to call this versus gis.plan, gis.answer, or gis.run, and no prerequisites or exclusions are given. The agent must infer that this is a discovery entry point from the name and verb alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a GIS workflow plan from a natural-language prompt.
Returns a JSON plan with inputs, outputs, assumptions, and ordered steps.
Does NOT execute anything.
If the plan has status "needs_clarification", use gis.answer() to provide
answers and get an updated plan.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behavior: it returns a JSON plan with inputs, outputs, assumptions, and ordered steps, and it does not execute anything. It also explains the clarification loop via gis.answer(), though it does not mention side effects, auth needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded: purpose first, return shape second, non-execution third, follow-up handling last. Every sentence adds distinct value with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description needn't document return fields exhaustively, and it still summarizes the plan structure. It covers the critical non-execution guarantee and the clarification follow-up, though it leaves the broader workflow relationship to gis.run_plan implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single 'prompt' parameter. The description adds that the prompt is natural-language, which is useful, but it does not clarify prompt format, examples, constraints, or what makes a prompt sufficient versus one that yields 'needs_clarification.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Generate a GIS workflow plan from a natural-language prompt.' It explicitly distinguishes itself from execution tools by saying 'Does NOT execute anything,' which is the key differentiator from siblings like gis.run and gis.run_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use gis.answer() when the returned plan has status 'needs_clarification.' It implies this tool is for planning rather than execution, but it does not explicitly say when to call gis.plan versus gis.run_plan in the normal success path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a blocked execution after a confirm step.
Args:
resume_token: The token from the blocked RunReport.
approved: True to proceed past the confirmation, False to abort.
| Name | Required | Description | Default |
|---|---|---|---|
| approved | Yes | ||
| resume_token | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose the key fork — approved=True proceeds past confirmation, False aborts — but says nothing about token expiry, what aborting does to prior work, or permission requirements, which matters for a state-changing confirmation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence states the action and its precondition, followed by a compact Args block that adds only parameter meaning. No filler, though the docstring-style formatting is slightly verbose versus inline phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema (so return values need no explanation), the description covers the trigger state and both parameter meanings. Error and expiry behavior are the remaining omissions, but they are modest against this tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it largely does: resume_token is sourced explicitly ('the token from the blocked RunReport') and approved's boolean polarity is spelled out in both directions. Minor gaps remain (token format/lifetime) but the ambiguous boolean is fully clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and object ('Resume a blocked execution') plus the trigger state ('after a confirm step'), which is clearly distinct from siblings like gis.run or gis.run_plan. It does not explicitly contrast itself with those siblings, keeping it at a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Resume a blocked execution after a confirm step' establishes a clear precondition for use, and the approved flag documents the two branches (proceed vs abort). No explicit exclusions or named alternatives are given, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plan AND execute a GIS workflow from a natural-language prompt.
Steps: gather QGIS context -> generate plan -> validate -> execute.
If the plan needs clarification, returns the questions (no execution).
If a confirm step is reached, returns a blocked report with a
resume_token -- use gis.resume() to continue.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses pipeline stages and conditional outcomes, including no execution on clarification and a blocked report with resume_token on confirmation. It omits side effects or destructive potential of 'execute', permissions, and what a GIS workflow may modify in the QGIS context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads 'Plan AND execute a GIS workflow from a natural-language prompt' and then uses a compact step list plus conditional outcomes. Every sentence contributes; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex orchestrator with an output schema, and the description explains the main flow and branch outcomes. With no annotations, however, it should also cover side effects, prerequisites, and how it relates to sibling planning tools. Return values are adequately supported by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the single required prompt parameter. The description adds that the prompt is natural-language, but gives no examples, scope, or constraints. This partially compensates for the schema gap but leaves parameter semantics thin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: plan AND execute a GIS workflow from a natural-language prompt. The step sequence makes clear it is an end-to-end orchestrator. It only partially distinguishes from siblings, since it names gis.resume for continuation but does not explicitly contrast with gis.plan or gis.run_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the workflow and branch behavior: clarification returns questions without execution, and a confirm step returns a blocked report with a resume_token for gis.resume. However, it does not say when to choose this tool over gis.plan or gis.run_plan for plan-only or execute-only scenarios. Selection guidance is implied by 'Plan AND execute' rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a specific plan JSON (e.g. from gis.plan, possibly edited).
Use this for the plan -> review -> edit -> execute workflow.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_json | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations at all, so the description carries the full burden. It says 'execute', implying side effects, but discloses nothing about permissions, validation of the plan, failure modes, or reversibility. Only the existence of an output schema relieves it of describing return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, the core action front-loaded. No wasted words, though the trailing workflow line could have carried more routing information for the same length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter and an output schema, the basics are present, and the plan provenance note is helpful. But for a mutation tool with zero annotations, the absence of side-effect, permission, and gis.run-vs-run_plan guidance leaves real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for the single plan_json string, so the description must compensate. It does partially: it tells the agent the JSON typically comes from gis.plan and may be edited before execution, which is meaningful semantics for an otherwise undocumented string. It still says nothing about format, size, or how invalid plans are handled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: execute a plan JSON, plus the provenance of the input ('e.g. from gis.plan, possibly edited'). This differentiates it from gis.plan (which produces the JSON) without needing the schema, though it doesn't contrast with the similarly named gis.run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives a workflow context (plan -> review -> edit -> execute), which implies when to use it. But it never says when NOT to use it, and crucially does not distinguish it from the sibling gis.run, so an agent must guess which entry point applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0gis.answergis.diagnosegis.explain_last_rungis.list_capabilitiesgis.plangis.resumegis.rungis.run_planScored across 8 tools
The core tools are mostly distinct: gis.plan only plans, gis.run plans and executes, and gis.run_plan executes a supplied plan. gis.answer and gis.resume target separate clarification and confirmation states, though the boundary between gis.run and gis.run_plan could still cause occasional misselection.
All tools use the gis. namespace with lower snake_case and action-oriented names such as run_plan, list_capabilities, and explain_last_run. The pattern is predictable throughout.
Eight tools is well-scoped for a GIS workflow assistant covering planning, execution, clarification, resumption, diagnosis, and inspection. Each tool appears to earn its place without filler.
The set covers the main workflow lifecycle: plan, clarify, execute, resume, diagnose, and inspect the last run, plus list capabilities. Minor gaps remain, such as no documented clarification path for gis.run and no run history beyond explain_last_run, but agents can work around these.
Ask in plain English, get a rendered, shareable map from live public data. 24 geospatial tools.
Checked language for AI-written agent workflows: limits, cost and data flows known before running.
GIS tools for AI agents: 65 free tools + 8 paid (hazard/site-scouting/GeoJSON export)
Verifiable Earth ground truth for AI agents: water, hazard, ground stability, resource, with proof.