Mapsource Geospatial API

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context about access requirements: 'Catalog is free; tile requests require a subscription key.' This goes beyond annotations to clarify authentication/usage conditions, which is a notable behavioral disclosure.

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, with the core discovery purpose front-loaded and the access caveat placed second. Every clause adds meaningful information, and there is no filler or redundancy.

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 parameter-less catalog discovery tool with no output schema, the description is complete: it states what will be discovered, the access model (free catalog vs. subscription-key tile requests), and implies a read-only operation consistent with annotations. Nothing essential is missing for an agent to invoke it correctly.

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 the baseline is 4. The description does not need to elaborate on parameter meaning, and its mention of what can be discovered (templates, date, attribution, header authentication) sufficiently conveys the tool's scope without any parameter-related ambiguity.

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 'Discover' and names the exact resources: CARTO Dark Matter and Positron raster tile templates, snapshot date, attribution, and header authentication. It clearly differentiates this catalog tool from the sibling tools (elevation, find_features, overpass_query, service_status) which serve unrelated purposes.

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 usage for discovering basemap catalog information, but it does not explicitly state when to choose this tool over alternatives or provide any exclusion conditions. The free-vs-subscription note gives context about access, but not about selection among sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses important behavioral context: authentication requirements, shared REST quota rate implications, and output units in meters. It also adds a safety caveat. This is substantial value over the structured metadata alone.

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 short sentences with no filler. The core purpose is front-loaded, followed by essential prerequisites and usage caveats. Every sentence earns its place.

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 simple read-only point-elevation tool with two fully documented parameters and no output schema, the description is complete: it explains what is returned, in what unit, under what authentication and quota constraints, and warns about inappropriate uses. No critical information is missing for an agent to invoke it correctly.

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 input schema already fully documents both parameters with names, ranges, and descriptions, so the description adds no additional parameter-level meaning beyond saying 'at lat/lon.' With 100% schema coverage, a baseline score of 3 is appropriate.

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 clearly states that the tool samples ground elevation in meters at a lat/lon coordinate, with a specific verb and resource. This sets it apart from sibling tools like basemap_catalog, find_features, overpass_query, and service_status, which serve different geographic or status-related purposes.

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: it requires a subscription API key, shares REST quota, and explicitly warns against navigation or safety-critical use. It does not mention alternative sibling tools by name, so it stops short of a 5, but the guidance is concrete and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It reveals the return content ('OSM geometry and tags'), the auth/payment requirement, and the important caveat that fixture results are test data rather than real local search results. This goes well beyond a generic statement, though it does not describe every edge case such as rate limiting or result ordering.

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 crisp sentences: what it finds, what it returns, and the critical prerequisites/caveats. There is no filler, and the most important scoping information is front-loaded.

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 there is no output schema and no annotations, the definition is fairly complete: it covers categories, bbox, limit behavior, return type, payment, and the fixture-data warning. A bit more detail about the exact response structure or coordinate conventions would make it fully self-contained, but the essential information is present.

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 only 33%, so the description must compensate. It does mention the feature categories and bounding-box constraint, and the schema documents category and limit well. However, the four coordinate parameters have no schema descriptions and the main description does not explain units or ordering, so the agent still has to infer semantics from the parameter names.

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 ('Find') plus an explicit list of feature categories and a bounding-box scope, so the tool's purpose is unmistakable. The schema's category enum further clarifies that this is for predefined OSM categories, with overpass_query for arbitrary tags, which helps distinguish it from sibling tools.

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 context: use for predefined feature categories within an explicit small bounding box, with a payment prerequisite and a warning to check service_status for fixture data. The category parameter description adds the alternative 'use overpass_query for arbitrary OSM tags', though the main description itself does not explicitly spell out all when-not-to-use conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the behavioral disclosure burden. It discloses payment requirements, the bounded-output constraint, the attic-query prohibition, and the dependency on service_status. It does not cover rate limits, error behavior, or result format, but the critical operational constraints are surfaced.

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 dense sentences with no filler: the first front-loads the purpose and scope, and the second lists requirements and operational cautions. Every clause contributes distinct information, making it both concise and well-structured.

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 complex Overpass QL tool without an output schema or annotations, the description leaves out the return shape, how 'global results' are defined, and how payment approval is verified. It covers important preconditions but is not fully self-sufficient for an agent deciding whether and how to invoke the 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?

The schema already documents the query parameter at 100% coverage, including that it must be a complete bounded Overpass QL query with explicit timeout and output limit. The tool description mostly restates 'bounded output' without adding syntax, format, or additional semantic details beyond the schema.

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 clearly states a specific verb, 'Execute Overpass QL,' and the resource, 'OSM nodes, ways, and relations,' while adding the key constraint of 'bounded output.' This sufficiently differentiates it from siblings like basemap_catalog and service_status by making both the domain and the operation explicit.

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 explicit preconditions: subscription or approved x402 payment, no historical attic queries, and checking service_status before claiming global results. It provides clear exclusions and usage context, though it does not explicitly name an alternative tool or say 'use X instead.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full transparency burden. It discloses that the call is free and that it should precede dependent queries, which are meaningful behavioral traits. 'Check' conveys read-only intent without claiming side effects. It could add more details about response behavior, but for a simple status tool the disclosure is solid.

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 a single, scannable sentence. It front-loads the action and resource, then lists the key status dimensions, closing with the critical usage directive. Every clause earns its place with no redundancy.

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 zero-parameter tool with no output schema, the description communicates purpose, cost, and timing in a compact way. It does not spell out the response format, but the listed status categories imply what the agent will receive. This is nearly complete for the tool's simplicity, though a short note on return shape would make it fully self-contained.

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 parameter semantics are trivially satisfied. The description adds meaning about what the status covers without needing to explain parameters. Baseline 4 is appropriate for a parameterless tool.

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 clearly states a specific verb ('Check') and a distinct resource (service status), enumerating concrete aspects it covers: engine readiness, fixture versus planet data, freshness, and payment mode. This distinguishes it from the sibling data-query tools 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?

The description provides explicit guidance on when to use the tool: 'call before relying on query results.' It also notes the tool is free, which is relevant for cost-sensitive agents. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it falls just 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.