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

Annotations declare destructiveHint=true and idempotentHint=false, and the description explains exactly why: repeated calls with the same name store duplicates, and adding to a full demo set silently deletes the oldest boundary. It also discloses rejection behavior (self-intersecting shapes, >50 points refused unbilled) that the annotations cannot express.

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 with the core action and the lookup consequence, then proceeds through prerequisites, geometry rules, plan limits and return shape in a logical order. It is long, but nearly every sentence carries a constraint the agent needs; the demo-key paragraph is the only slightly bloated section.

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?

There is no output schema, yet the description names the returned fields (id, set, name, properties, pointCount, createdAt). Combined with prerequisites, geometry limits and failure modes, an agent has everything needed to call it correctly and interpret the result.

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 100%, so the schema already documents ring closure and [longitude, latitude] ordering. The description nonetheless adds constraints not present in the schema: geometry must be a single Polygon (not MultiPolygon/Feature/FeatureCollection), a hard 50-point cap on every plan including the closing point, and demo-key restrictions on properties values.

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 ('Adds ONE polygon to an existing boundary set') and ties it to the downstream effect on lookup_location. It is clearly distinguished from create_boundary_set and update_boundary by the 'each call creates a new boundary' 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?

Explicitly names the prerequisite tool (create_boundary_set), the dashboard step required before lookups match, and the alternative action for MultiPolygons (add each part separately) or oversized shapes (simplify or split). It also scopes demo-key usage with a 'never upload anything private' warning.

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?

Discloses a non-obvious behavioral trait that no annotation conveys: a new set is created unavailable and ungranted, so it matches nothing until both are changed. It explains the root cause (grants are addressed by API key id, which the server cannot discover about itself) and prescribes the exact remediation and dashboard URL. This is consistent with readOnlyHint=false and openWorldHint=true.

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 purpose is front-loaded in the first clause and the critical caveat follows, with the actionable instruction to relay to the user placed last. It is a bit long, but nearly every sentence carries decision-relevant information; the 'not a bug' framing is slightly defensive but justified given the surprising behavior.

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?

Covers creation semantics, the grant gap, and the required user follow-up thoroughly for a mutating one-parameter tool. With no output schema, it does not say whether the new set's identifier is returned or how an agent should reference the set in a subsequent add_boundary call, which is the remaining gap.

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 100% and the single 'name' parameter is fully documented in the schema, including the pattern constraint, so the description adds no syntax or format detail beyond it. The phrase 'named set' only echoes what the schema already says, making baseline 3 correct.

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 ('Creates an empty named set to hold your own polygons') and illustrates the kind of content it holds (delivery zones, service areas, sales territories). This clearly separates it from add_boundary, which populates an existing set.

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?

Implies the create-then-add workflow ('this tool can create the set and add boundaries to it') and gives concrete use cases, so an agent knows when to reach for it. It stops short of explicitly naming an alternative or stating a when-not condition relative to list_boundary_sets or add_boundary.

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?

Annotations only declare readOnlyHint and openWorldHint; the description carries the real behavioral load: billing (one lookup per address, found or not, null still billed), unbilled refusal for uncovered countries, country as a hard filter vs region as a preference, what confidence and ambiguous actually mean, and that sets/base are free in the same call. Far beyond what the annotations supply.

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 correctly with the one-address-per-call constraint and the precision warning, and nearly every paragraph carries operational information. It is nevertheless very long and repeats itself slightly ("1 lookup per address" vs "One address per call, deliberately", plus the multi-paragraph "Long Street, Cape Town" illustration), which costs it the top mark.

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?

No output schema exists, so the description must describe returns — and it does: precision values, matched.crossStreet, matched.site, matched.locality vs matched.suburb, result.alternatives with suburb/distance/direction, and result null. Combined with the precision-to-action mapping, an agent has everything needed to call this and interpret the response.

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 already 100%, yet the description still adds non-obvious semantics: q vs address are mutually exclusive and pre-split input "matches better", country is a hard filter, region "only ranks streets inside it", and sets/base answer zone questions at no extra cost. It also explains that streetGeometry is trimmed and only worth requesting if something will draw it.

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?

Opens with a specific verb+resource+scope: "Turn ONE address into a point, with an honest account of how much of it was found. Built for deliveries. South Africa today." It also distinguishes itself from the reverse-geocoding sibling at the end ("a coordinate to an address — that is lookup_location"). An agent can tell what this does and what it does not without opening the schema.

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?

Explicit when-to-use routing per precision level (dispatch / ask for a pin / ask the customer), explicit when-not (business or landmark name search, reverse geocoding, bulk rows which should use the API's batch endpoint), and explicit exclusivity between q and address. This is about as complete a routing guide as a tool description gets.

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?

Annotations only declare readOnlyHint/openWorldHint, so the description carries real behavioral weight and does: cost of 10 LOOKUPS with X-Lookups-Remaining as truth, free-flow (no traffic) durations, 403 caps unbilled vs 422 failures billed, snapping with snapDistanceMeters, exposure skipping above 1,000 zones, and truck speed capping. This is exactly the non-obvious context an agent needs.

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?

Well front-loaded with purpose then COST, and organized into scannable labeled paragraphs. It is long, and a few points (geometry rationale, free-flow warning) are restated across description and schema descriptions, costing some density.

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 10-parameter, nested-object, no-output-schema routing tool, the description covers billing, failure modes, plan caps, snapping, boundary-set semantics, and result contents (distance, duration, steps). An agent could invoke it correctly without reading anything else.

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 100%, so baseline is 3, but the description adds meaning beyond the schema: avoidSets/exposureSets are confirmed to be account boundary sets resolved via list_boundary_sets, zones containing a location are skipped and reported in avoid.skipped, and missing weightTonnes triggers an 80 km/h cap. That is substantive semantics the schema alone does not convey.

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?

Opens with a specific verb+resource+scope: 'A driving, cycling, walking or truck route from the first location to the last, via any in between, with distance, duration and turn-by-turn steps.' It also draws hard boundaries against siblings ('Not for: distance matrices, isochrones or live traffic ... that is lookup_location').

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?

Explicit when-to-use and when-not-to-use: names lookup_location for area questions, warns against looping to compare options, tells the agent to request routeGeometry only when something will draw it, and explains avoidSets vs exposureSets selection criteria. Nothing is left to inference.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that: it discloses the response contents (counts and granted keys per set) and a non-obvious caveat that grantedKeys is always empty on the shared demo key. It stops short of describing pagination, ordering, or error behavior.

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?

Three sentences, front-loaded with the core purpose, followed by only the semantics needed to interpret the output. Every sentence earns its place and there is no repetition of the schema or annotations.

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 read tool with annotations and no output schema, the description is nearly complete: it covers what is returned and a key edge case. Minor gaps remain around response ordering, empty-state behavior, and pagination, but an agent has enough to call and interpret 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?

There are zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate at the input level. The description does explain the meaning of return fields, which is useful because no output schema exists, but parameter semantics themselves are not applicable.

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 ('Lists the boundary sets on this account') and even enumerates the returned fields (boundary counts, granted API keys). It is clearly distinct from the mutating siblings like create_boundary_set and add_boundary, though it does not explicitly name an alternative tool.

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 supplies interpretive context ('a set only matches during a lookup when it is available AND granted to the key making the call'), which implies why an agent would call it. However, it never explicitly says when to use this tool versus lookup_location or how to act on the results, leaving routing to inference.

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?

Annotations only declare readOnlyHint and openWorldHint, so the description carries the behavioral burden and does so richly: it discloses billing semantics (one call = one billed lookup regardless of layers, and a no-match call still bills), that the errors array is always present and reports skipped/ungranted boundary sets while the call still succeeds, and the distinction between the two kinds of null for streets. This is far beyond what the annotations supply.

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 definition is front-loaded (purpose, then Use for / alternatives, then caveats, then a dedicated STREETS section) and nearly every sentence carries information that changes agent behavior. It is dense and long, and lines like 'caveats worth repeating to the user' are slightly meta/marketing-toned, but no section is genuinely 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?

With eight parameters, no output schema, and only two required params, the description compensates thoroughly: it explains the shape of street answers, the always-present errors array, the meaning of each null variant, unit and code formats, and the billing model. An agent has everything needed to call it correctly and interpret the response without a 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?

Although schema coverage is 100%, the description adds meaning the schema does not: base.street always returns exactly three answers (5 m, 20 m, unlimited) with named fields, streetNumber and postcode are STRINGS with examples, streetGeometry is trimmed to ~250 m and implies the street layer, and 'add street to base' is the opt-in mechanic. Null-vs-null-field semantics for street results are spelled out, which the schema cannot express.

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 first sentence states a specific verb (reverse geocode) plus the exact resource (administrative areas containing the coordinate) and enumerates the outputs: country, region, municipality with ISO 3166 codes, optional street, plus uploaded boundary-set matches. It also explicitly names the sibling it is not (geocode_address for the opposite direction, get_route for routes), so an agent can disambiguate without opening any schema.

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?

A dedicated 'Use for:' block lists the concrete tasks (country/region/municipality lookup, street identification, geofence checks against own polygons, tagging with region codes) and names the alternatives with their conditions. It adds explicit exclusions: 'Do NOT use for place search by name or for fetching boundary geometry,' and cites a cost differential versus get_route. Nothing is left to inference.

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?

Annotations already declare destructiveHint, idempotentHint and openWorldHint, but the description goes further: it explains what survives the replacement (identity and properties), how ambiguous name resolution behaves (ids returned, caller asked to pick one), the 50-point cap, that a rejected shape is unbilled, and the account boundary. That is exactly the context annotations cannot carry.

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?

Five short sentences, front-loaded with the operation and its invariant (id/name/properties preserved), then the when-to-use, then the error path. No sentence restates the name or title without adding information.

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 mutation with a nested GeoJSON payload and no output schema, the description covers validation limits, ambiguity handling and preservation semantics. The one gap is what a successful call returns or how to confirm the new shape landed, which the agent has to discover at runtime.

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 100%, so the baseline is 3, but the description adds real resolving semantics beyond the schema: naming by set+name performs an id lookup, and duplicate names produce an id list rather than an arbitrary pick. It does not add syntax detail for the geometry rings, which is left entirely to 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?

States a specific verb and resource ('Replace the shape of ONE existing boundary') and immediately scopes it by what is preserved: id, name, properties, set. The capitalization of ONE disambiguates it from bulk or create operations, so an agent can tell it apart from add_boundary without opening either schema.

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?

Gives the positive case ('Use this to fix or move a zone') and an explicit anti-pattern with the reason ('Do NOT delete it and add it again: that gives it a new id and loses the properties'). It also states the account restriction ('Only boundaries on this account can be changed'), leaving nothing to inference.

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