InstaMaps

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses determinism (rules and tools, never model-invented values), that `reading` explains how the question was interpreted, the 200-row cap and mode tradeoffs, that zero results come with a diagnosis, address-based geocoding fallback, and geographic coverage limits. This is exactly the behavioural context an agent needs before calling.

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 purpose and constraint, and nearly every clause carries information. It is dense to the point of being run-on, with long parenthetical example lists that slow scanning, so it is efficient but not maximally tight.

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 7-parameter tool with nested source objects and no output schema, it covers modes, return shape (rows vs match vector vs reading), size limits, zero-result behaviour and geo scope well. It stops short of describing the shape of the `reading` or diagnosis output, which is the one 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 already 86%, but the description adds real meaning the schema lacks, notably explaining each mode value (rows returns matching rows, match returns one TRUE/FALSE per input row in order, why returns the reading) which the bare enum does not, plus the 5,000-row limit and the intent of reference_records.

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 (answer a plain-English question about a table of rows) and scopes it concretely with examples of filters, place questions, ranking, counts/group-bys and two-list questions. It is clearly distinguishable from siblings like filter_by_location or find_nearby, which are shape-based lookups rather than free-text question answering.

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 explicit operating guidance: use mode rows for the first 200 matches and mode match for larger tables, use reference_records for two-list questions, and place tools are UK-only with flood being England/US. It does not, however, name sibling tools to use instead of this one, so the routing guidance is present but not framed as alternatives.

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 readOnly/openWorld/non-destructive, so safety is covered; the description adds real behavior beyond that — the 500-record cap, automatic background execution past 500 rows with job_id/get_job, aggregation of a value column, and that render returns a link plus GeoJSON and KML. It stops short of stating auth requirements or failure handling for unplaced rows beyond 'the reason'.

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 core is front-loaded, but the single dense paragraph packs parentheticals, asides ('the claims view', 'a place near an edge is worth a look either way') and mixed concerns into one block. Most content earns its place, yet the rambling style makes it harder to scan than it needs to be for an 11-parameter 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?

For a complex, 11-parameter, nested-schema tool with no output schema, the description covers the essentials: result record shape, distance banding, limits, background jobs, and map rendering outputs. Only minor gaps remain (peril/region/min_level semantics, permission requirements).

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 only 55%, but the description compensates well: it explains the source-by-reference pattern (sheet/file/run, header-based column discovery), the records vs addresses split, the near_km default of 5, the value_field auto-detection names, and the background flag. Coverage gaps remain for perils, region, min_level and title, which the description never explains.

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: take up to 500 addresses/points and test them 'against the warnings in force now', classifying each as inside, near, clear, or unplaced. It explicitly names the sibling it draws warnings from (get_live_hazards), so an agent can distinguish it from the raw hazard listing without opening a 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 concrete routing guidance: use source/run as a background job for large inputs, and 'Set render to true only when the user wants to keep or share the map' with update_map as the follow-up. It lacks explicit when-not-this-tool exclusions versus siblings like get_area_risk or find_nearby, but the conditions it does state are 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real operational context beyond them: per-run input cap of 5,000 rows, output truncated to the first 300 combined rows, left-outer join semantics ('places in only some runs are kept and say which'), and the row-filtering behavior of only_changed. It does not explain ordering of output or how run names are disambiguated, which is a minor gap.

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 core action (join runs on record_key, 2-6 runs) is front-loaded, and the limits and semantics follow. It is one very long run-on sentence with a few embedded clauses, so it is dense rather than cleanly structured, but nearly every clause carries 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?

With no output schema, the description covers what matters for a join tool: valid inputs, key column, join semantics for partial matches, compare behavior, filtering, and both input and output row limits. Missing only output row ordering and how truncated rows are signalled.

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 80%, and the description still adds meaning: how run columns are namespaced ('each run's columns kept separate under its name'), that compare produces numeric deltas vs. text change flags, and that places missing from some runs are retained. This goes beyond restating the schema defaults.

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 (join) and resource (two to six kept runs), names the join key (record_key), and specifies the scope (2-6 runs, oldest first). No sibling tool does joins on prior runs, so an agent can identify this tool immediately.

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 concrete sourcing context ('run_ids from earlier answers, or tables such as dated tabs in Drive') and a worked example ('sites whose nearest A&E got further away since September') that implies when this tool applies. It does not name a when-not condition or an alternative sibling, but none of the siblings overlap meaningfully.

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 destructiveHint=true annotation, the description discloses concrete consequences: the link stops working and pins, versions, logbook and photos are lost; it is not undoable; and other people's maps are reported as not found. This richly supplements what the annotations already flag.

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 the core action and its destructiveness first, then the confirmation and alternative guidance. It is on the longer side but almost every clause carries actionable meaning for a destructive 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?

For a destructive mutation with full annotation coverage and a trivial schema, the description fills in the return/edge behavior (link dies, non-owned maps reported as not found) and the confirmation protocol, leaving nothing an agent needs missing.

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 'maps' parameter is already documented as map_ids or links. The description adds mild context by indicating which link forms and sources are valid, but does not expand on syntax or limits beyond the schema, so the baseline 3 holds.

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 (deletes) and resource (the person's own maps), and further scopes it to maps created via render_map or the InstaMaps Sheets add-on. An agent can clearly distinguish this from update_map, get_map, or render_map.

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 gives the when-to-use condition (only when the person asks in so many words), the required confirmation workflow (name each map by title and confirm first), and names the alternative for the ambiguous case (call get_map with no map to let them tick maps). 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?

Far exceeds what the readOnly/idempotent annotations convey: it discloses capacity limits (100 addresses per call, 2000 records, 25 sites), the straight-line distance model, that held-for-review records are flagged and unplaceable records are listed 'never silently counted in or out', the compact >200-record output format, and that the map renders in-chat by itself. This is exactly the behavioral context 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?

The core question is front-loaded in the first sentence and every subsequent sentence adds distinct, non-redundant information (limits, distance model, flags, compact output, render behavior). The structure is a dense single block of long sentences rather than scannable segments, which slightly hurts readability, but there is little 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 no output schema, the description carries the return-value burden and does so thoroughly: it defines the per-record site+distance output, the flagged/unplaced handling, the compact [id, site, miles] form over 200 records, and the render payload (link, GeoJSON, KML). For a 10-param, nested-object, open-world tool, nothing an agent needs to call it correctly appears to be missing.

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, and the description adds meaning on top: it explains when to set render (keep/share) and that it returns a link, GeoJSON and KML, and it supplies capacity constraints (2000 records, 25 sites, 100 addresses) that constrain sites/records/nearest_n but are not stated in those schemas. It does not elaborate on every parameter, so it is above baseline but not exhaustive.

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 opening sentence states a specific compound operation with concrete verb and resource: find records within a distance of sites, each record's nearest site, and/or the N nearest records per site. The clause 'Distances are straight-line (great-circle), not driving' plus the record/site framing cleanly separates it from driving-focused siblings such as get_road_distances and get_travel_time_area.

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 conditional usage guidance for render ('Set render to true only when the user wants to keep or share the map') and cross-references update_map for later edits and get_job/write_to_sheet for background jobs. It stops short of an explicit when-to-use-this-vs-sibling statement (e.g., versus find_nearby or get_road_distances), so it is clear context without full exclusions.

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 cover the safety profile (readOnly, idempotent, non-destructive, not open-world), and the description goes well beyond them with hard limits (500 addresses, 300 places per answer, n up to 50), the count-mode exemption from that cap, the behavior of an unrecognized category word (returns the full list), source-quality caveats ('classic amenities are well covered, trades patchily'), and background-job throttling. Nothing here contradicts the annotations.

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 and routing are front-loaded, and most sentences carry distinct information (limits, categories, source comparison). It is a dense paragraph heavy with parentheticals, which slightly impedes scanning, but there is little pure 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?

For a tool with nested source objects, three modes and no output schema, the description covers inputs, limits, fallbacks and the cross-tool decision well. The shape of results per mode is only lightly implied (the schema notes results come back under the caller's id), so a touch more on return content would make it fully complete.

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?

With 75% schema coverage the schema already documents n, radius_km defaults and the source block, but the description adds meaning the schema lacks: the actual category vocabulary (schema leaves 'category' undocumented), the records × n relationship behind the 300-place cap, and mode semantics. It does not explain the id/name/address fields beyond what the schema says, so it stops short of a 5.

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+resource+scope: 'the nearest places of a kind' for up to 500 addresses/points in the UK and US, and enumerates its three operating modes (nearest, count, list). It explicitly differentiates itself from sibling find_official_places by naming the data sources behind each (open map index vs CQC/NHS registers), so an agent can distinguish the two 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 explicit routing: use this for open-map categories (pharmacy, station, supermarket, ...), but use find_official_places for A&E, hospitals, GP practices, care homes, dentists and NHS pharmacies in England 'with ratings', because open map data mixes these up. It also defines when each mode applies (count has no result cap; nearest/list cap at 300). This is close to a complete when/when-not/alternative statement.

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 cover the read-only, idempotent, open-world safety profile, so the description earns credit for adding provenance and failure behavior: exact register coverage by geography, returned IDs (CQC location, ODS, UPRN, FHRS) plus official page and source, and the rule that an unmatched row 'says why and lists what is registered there.' A useful auth note (sheet must be shared with the service account or link-viewable) is also present, though rate limits are not addressed.

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?

Content is dense and mostly earns its length given 14 parameters and 10 place kinds, but it is delivered as one sprawling paragraph with deep nested parentheses and run-on sentences, and it opens on an oblique phrase ('What open map data doesn't have') rather than the action. Readability and front-loading suffer even though little is pure 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?

Despite high complexity (14 params, nested `source` object, no output schema), the description covers register coverage, mode behavior, source-input handling, filters, batch limits (500/100), background-job behavior, and the fallback tool. Nothing an agent needs to invoke it correctly is missing.

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 high (~79%) with enums for kind and mode, so the baseline is 3; the description goes further by explaining mode=at semantics ('the registered place AT each address... send the business name as name'), the concrete rating vocabulary accepted by the `rating` filter, and the meaning of the NHS/independent and hygiene filters. This usefully compensates for the undocumented `kind` enum values left bare in 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 names the specific resource (official-register places: CQC, NHS pharmacy, FSA food businesses) and the specific verb/scope ('for up to 500 addresses or points... the nearest, how many within a radius, or a list'). It explicitly differentiates from its sibling: 'Use find_nearby for everything else (shops, stations, parks).' An agent can route confidently 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?

It spells out when to use each mode (nearest/count/list vs. mode=at for match-by-name), when to send the business name, which filters apply (rating, NHS/independent, food type, hygiene score), and the fallback (`find_nearby`). Exclusions and alternative are both explicit, including 'addresses outside a register are told so.'

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the distance metric (straight-line between centres), the counting rule (an area counts when its centre is inside), data provenance ('our own copy of the Census ZIP centres and the UK postcode centres'), and the run_id workflow with render returning a link plus GeoJSON and KML. That is rich behavioral context an agent cannot get from the annotations.

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 what the tool returns, then usage, then the sibling routing rule and the render caveat. Most sentences earn their place, though the pricing/provenance aside ('Free: our own copy…') and the render sentence could be tightened without losing decision-relevant 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?

There is no output schema, so the description carries the return-value burden and does so: nearest-first results with distance, a total count, and a run_id that can be written to a sheet or rendered, plus the render payload. Combined with the routing rule to filter_by_location, an agent has everything needed to call 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?

Schema coverage is 63%, so some parameters (unit, title, country, radius, limit) rely on the schema alone, but the description adds meaning where it matters most: render's side effects ('returns a link, GeoJSON and KML, and update_map can change it later') and the centre-input taxonomy. It is partly redundant with the center/granularity schema descriptions, so it is additive rather than fully compensating.

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 resource (US ZIP codes / UK postcode sectors or districts) with a precise scope qualifier (centres within a radius of a place, nearest first with distance). It also names the sibling it is not (filter_by_location) and the downstream tools it feeds (render_map, update_map), so an agent can place it 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?

Gives concrete use cases (service areas, delivery zones, direct-mail and ad targeting lists) and an explicit routing rule: 'For "who on MY list is within X miles", use filter_by_location instead.' It also conditions the optional render flag ('set render to true only when the user wants to keep or share the map'), which is exactly the when-to-use decision an agent must make.

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?

Goes well beyond the annotations: it explains determinism ('the same input always gets the same answer'), what the confidence score means, the status taxonomy, the precision taxonomy, that ordering is preserved, that unplaced rows carry a reason, and that overflow rows are not looked up. It also gives concrete coordinate formats accepted. Nothing an agent would be surprised by is left implicit.

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, which is good, but it is a dense wall of long parenthetical sentences. The confidence explanation ('our estimate of how often an answer that sure is right, being refitted against public address records') is verbose and could be one clause; several admin-field lists are repeated twice.

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 no output schema, the description carries the full burden of explaining returns, and it does: per-row status, coordinates, precision, confidence with evidence, building classification, admin parts, record_key, map_version, nearest_address for reverse geocoding, and CSV output columns. An agent knows what comes back in every mode.

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 six parameters are already documented in detail, and the description largely restates behavior rather than adding per-parameter meaning. It does add the accepted coordinate formats and the notion that flats/units match to their building, but it does not explain 'background', 'records' vs 'addresses', or 'columns' beyond what the schema says, so baseline 3 is right.

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 opening sentence gives a specific verb, resource, and scope ('Place up to 100 addresses in one call'), and the description also carves out a second capability ('this is also how to turn coordinates into addresses'), which no sibling tool name suggests. An agent can tell exactly what this does without reading 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?

It gives clear usage signals: batch up to 100, coordinates are placed as given, and rows past 100 come back as not looked up, with 'background' triggered automatically past 100 rows. It points at the write_to_sheet sibling for sheet output, but never explicitly says when to prefer find_nearby or get_location_facts instead, so routing is implied rather than stated.

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 readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context on top: source coverage boundaries (police.uk is England and Wales only; Environment Agency vs FEMA), the 'rows outside a source's coverage say so rather than guess' fallback, the 250-row cap, and the automatic background switch past 200 rows. It does not cover error behavior or rate limits, so it stops short of a 5.

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-loading is good (scope first, then per-metric detail), but the flood clause is a single sprawling run-on with nested parentheticals, and the render/background guidance is buried at the very end. Information density is high, yet the structure makes it hard to scan.

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 no output schema, 8 parameters and nested source/records objects, the description carries a lot and mostly delivers: it describes what comes back per metric (counts, zone, rank, 'says' sentence), what render returns, and how background jobs are retrieved via get_job/write_to_sheet. Only the exact result shape per metric remains underspecified.

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?

With 75% schema coverage the baseline is 3, but the description materially enriches the undocumented parameters: it enumerates the crime kinds, defines each flood comparison, lists the hazard kinds, and explains render's link/GeoJSON/KML return and background's job_id flow. It adds meaning well beyond the schema 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?

States a concrete verb and resource ('One risk fact for each of up to 250 addresses or points') and then spells out the three metrics (crime, flood, hazard) with their underlying sources. An agent can tell exactly what comes back, but the description never differentiates this static-risk tool from the near-named siblings get_live_hazards and check_live_hazards.

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 real conditional guidance: 'Set render to true only when the user wants to keep or share the map', the flood prospecting/renewals/book-of-business use case, and the background-job rule. It stops short of naming alternatives, so it never says when NOT to use this versus the live-hazard 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), lowering the bar, and the description still adds real behavioral content: the exact status vocabulary and the fact that partial progress, an ETA, and written-row info are returned. With no output schema, this return-value disclosure is genuinely useful. It does not cover polling cadence or job retention, so a 4 rather than 5.

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?

A single information-dense sentence with no filler; every clause (statuses, progress, ETA, run_id reuse, sheet output) earns its place. The nested-parenthesis chain around run_id is slightly harder to parse and the sentence opens with context rather than the action, costing it the top score.

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 low-complexity, single-parameter, read-only polling tool with no output schema, the description covers the return payload thoroughly and even documents how to reuse run_id downstream. The main omission is how to acquire job_id, which the 0%-coverage schema leaves entirely unaddressed.

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 is one parameter (job_id) with 0% schema description coverage, so the description must compensate. It partially does: 'a job a tool started' tells the agent the id refers to a previously launched job, but it never states the id format or explicitly where the agent obtains it. That is meaningful but incomplete compensation, matching the minimum-viable 3.

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 makes clear this tool reports on a background job started by another tool, and enumerates exactly what comes back: status (queued, running, done, failed), rows done of total, ETA in minutes, run_id, and sheet writes. No sibling tool covers this job-progress niche, so it is effectively self-differentiating. It falls short of a 5 only because the purpose is expressed as a noun phrase ('For a job... its status') rather than a plain statement of the action.

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 supplies the selecting condition implicitly: use this for a job 'a tool started (a list by reference bigger than one call)', i.e. long-running batch work. It also gives downstream usage guidance — reuse the returned run_id as source { run } in any tool or from_run in render_map. There is no explicit poll-until-done instruction or when-not guidance, which keeps it out of 5 territory.

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 cover the safety profile (readOnly, openWorld, non-destructive), and the description adds context the annotations cannot: a 10-minute refresh cadence, per-source provenance, and a data-quality caveat ('automatic estimates, rated a step lower'). It also discloses that render returns a link, GeoJSON and KML, and that update_map can later modify the result.

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 well with the core purpose in the opening clause, but the body is a dense ~200-word run-on that blends source enumeration, parameter explanation, and sibling cross-selling. Several clauses are decorative detail ('where the winds have already been') rather than decision-relevant, so it is over-stuffed rather than tight.

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 no output schema, the description carries the return-shape burden and does so: it lists the fields each hazard carries (kind, level, area, times, source link) and notes the map shows outlines. Combined with the source list, freshness, and parameter coverage, an agent has everything needed to call 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?

Schema coverage is 60% (title and render have no schema description), so the description must compensate. It fully explains render's semantics and return artifacts, and expands on the levels (severe, warning, watch, advisory) and peril categories in prose. Only the title parameter is never addressed, keeping it short of a 5.

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+resource (retrieves warnings and events in force right now) and enumerates the exact feeds involved (Environment Agency flood warnings, NWS warnings, USGS ShakeMap earthquakes, NHC storms, GDACS). It explicitly distinguishes itself from the sibling check_live_hazards ('Which of the user's own places are affected'). An agent can identify this as the global live-hazard feed 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?

Names the alternatives and the condition that selects each: check_live_hazards for the user's own places, render_map with a live_hazards layer for a keepable map. It even states an explicit when-not for a parameter: 'Set render to true only when the user wants to keep or share the map.' 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 establish readOnly, idempotent, closed-world and non-destructive, so the description is free to add what they cannot. It does: coverage gaps are stated explicitly ('held for Haringey only so far', council data that is 'not published by this council', never none), null-with-depends_on cases are spelled out (stadium events, pay bays, edge-of-zone, Christmas weekend), unplaceable addresses are returned with a reason, and background execution kicks in automatically past 150 rows via get_job. The density is a readability cost, but the behavioral disclosure is well above the annotation baseline.

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 intent is front-loaded and the opening line is strong, but the body collapses into a single run-on paragraph of stacked parentheticals and semicolon chains covering parking, permits, red routes, UPRNs and flood zones. Content that matters is present but not scannable; headers or bullet grouping by region/use case would cut length and raise comprehension.

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 seven-parameter tool with nested source/records objects and no output schema, the description carries a lot: it enumerates which facts come back per country, describes the shape of parking answers and the read-aloud sentence, notes permit_covers/with_your_permit, red_route, matched_as and did_you_mean, and covers the background-job path. It does not describe the general record-level result envelope (ok/errors) that the roads path gets, which is the main 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%, so the baseline is 3 and the schema already documents roads, records, source and background. The description still adds meaning: it explains that naming fields shortens the answer, maps field meaning by region (FEMA vs Environment Agency flood, parking_zone defaulting to Haringey), and clarifies that roads answers return in 'roads' rather than 'records' and that a street-only address yields whole_road: true.

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 opening sentence names a specific verb and resource: 'For up to 200 addresses or points, the official areas each one falls in, from our own copies of the official maps.' The per-country field lists (census tract, HUBZone, conservation area, flood zone) make clear this is an authoritative-areas lookup rather than a geocoder. It never names or excludes a sibling such as find_official_places or get_area_risk, so an agent must infer the boundary itself.

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?

Usage is routed by user intent rather than left abstract: 'for "which parking zone am I in, can I park here now?" send lat,lng or a full address with its postcode' and 'For a whole road ... send roads.' It also sets scope limits (200 records, Haringey-only parking, 'a guide, not an official determination'), but gives no when-not-to-use cases and no comparison against sibling tools that also answer location questions.

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 readOnly/idempotent/non-destructive, and the description still adds real behavior: the result is rendered in the chat, the layer view is capped at the first 500 pins, and the no-argument list doubles as an interactive picker where the person can tick and delete maps. That last point is a mild tension with destructiveHint=false (the tool itself is still a read), but it is disclosed rather than hidden.

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 opening sentence is a dense pile-up of return fields, and the use-case guidance is spread across four later sentences with repeated "use it when" phrasing. Content is valuable and mostly front-loaded, but it is longer and less scannable than it needs to be.

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 no output schema, the description carries the full burden and does so: it describes the returned link, downloads, layers/pins, version history, the 500-pin truncation, and the listing mode, plus how each mode is triggered. An agent can call this correctly with nothing left to infer.

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 goes further by explaining the semantic consequence of omitting map (list the person's own maps) and clarifies the special layer value "pins" for InstaMaps Sheets add-on maps. It adds meaning beyond the schema's terse parameter docs.

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?

Names a concrete verb+resource (read a kept map made with render_map) and enumerates the returned surface: link and downloads, layers with pin ids and fields, version and earlier versions, or a layer's pins. It is clearly distinguishable from render_map, update_map and delete_map, and it also states the zero-argument listing mode.

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 explicit when-to-use routing: call before update_map on a map from an earlier conversation, call with no arguments when the person asks to see their maps or supplies no link, and use the resulting list when they want to delete maps but haven't named them. Alternatives are named rather than implied.

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?

Goes well beyond annotations (which only cover read-only, idempotent, non-destructive) by disclosing the routing engine, traffic model, the straight-line fallback for unroutable journeys (Northern Ireland, islands) reported in `note`, and the two-tier summary. These are exactly the behavioural traits an agent must know before trusting the numbers.

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?

Four tight sentences, front-loaded with capacity, scope and routing context; each sentence carries distinct information. Only mild density of scoping qualifiers keeps it from a 5.

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 partially compensates by describing the summary contents and the `note` field for unroutable journeys. It is very complete for a read-only geo tool, though background-job chaining (get_job/write_to_sheet) is left entirely to the 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?

Schema coverage is 100%, so the schema already documents all five parameters. Description adds marginal value by naming accepted endpoint forms (addresses, UK postcodes/districts like CO10, US addresses, lat/lng) and the 100-journey cap, but this is largely mirrored in 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+resource (road miles, km and drive time for journeys) with concrete scope (up to 100 per call, GB and US roads). The 'our own routing' detail distinguishes it from siblings like plan_routes and get_travel_time_area without needing to open 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?

Capacity (up to 100 journeys) and routing model (normal traffic, no live traffic) are stated, implying when this tool fits, but no explicit when-to-use vs when-not-to-use guidance and no named alternative (plan_routes, get_travel_time_area) is given.

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 the safe read-only/idempotent profile, and the description adds substantially more: routing data provenance (own routing on GB/US roads, open routing service elsewhere), the traffic model choices, automatic in-chat map rendering, what render returns (link, GeoJSON, KML), and the background-job flow with get_job/write_to_sheet.

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?

Dense and front-loaded: the core purpose and the primary example lead, with advanced controls (include_geometry, render) after. The long opening sentence and some run-on clauses cost readability, but nearly every sentence carries 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?

Covers a complex, 11-parameter, nested-schema tool well despite having no output schema, including return artifacts and the async job path. Minor gap: it states '200 addresses' while the schema allows 500, and error/failure behavior is not addressed.

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?

With 73% schema coverage the schema already documents much, but the description still adds real meaning: include_geometry yields larger GeoJSON polygons, source accepts a Google Sheets link/Drive file/run_id with header-based column detection, and records ids are used to merge results back. A few params (mode, minutes, origin) are self-evident and left 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+resource (compute the reachable area from one origin), its scope (5–60 min, up to three bands, drive/walk/cycle, with size), and the secondary record-classification mode. An agent can distinguish it from siblings like plan_routes, find_nearby, get_road_distances and filter_by_location 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?

Gives explicit conditions for render ('only when the user wants to keep or share the map'), notes the bands render automatically, and points to update_map for later edits. It does not, however, route the agent away from adjacent siblings such as find_nearby, filter_by_location or get_road_distances, so the when-not-to-use guidance is incomplete.

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 readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine behavioral context beyond that: unroutable stops surface in `unassigned` with a reason, over-limit shifts emit `driving_limit_warning`, low bridges come back as `low_bridges`, and the map auto-renders without a road line. It stops short of describing pagination/size limits on the returned link sets.

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?

Long but information-dense and front-loaded: purpose first, then output/warning behavior, then the render caveat. Each sentence carries new signal (link chaining logic, warnings, render semantics), though the middle discussion of Google Maps link chaining is more detailed than an agent strictly needs to select 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?

For a 10-parameter tool with nested `source` and no output schema, the description goes a long way toward explaining what comes back (chained maps links, `unassigned`, warnings) and when render matters. The remaining gap is the `source` ingestion variants and return_to_depot behavior, which are only covered by the schema text.

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 70%, so the schema documents most fields (depot, stops, traffic, service_minutes). The description re-states scope that maps onto drivers/shift_hours and elaborates render's return values (link, GeoJSON, KML), but leaves return_to_depot and the source column-detection options unexplained beyond what the schema already says.

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 names a specific verb and resource with hard scope: 'Split up to 100 stops across up to 10 drivers from one depot and put each driver's stops in the best order on real roads.' It is instantly distinguishable from the other map/route siblings (render_map, update_map, get_road_distances) because it produces a multi-driver ordered plan rather than a single artifact.

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 explicit conditional use for render ('Set render to true only when the user wants to keep or share the map') and notes update_map can modify a kept map afterwards. It does not name when to prefer get_road_distances, get_travel_time_area, or render_map for simpler needs, so exclusion guidance is incomplete but present.

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?

Goes well beyond the annotations, disclosing the same-title replacement behavior ('that map replaced in place, same link, the old version kept'), the returned map_id, and hard limits (20 layers, 2,500 pins, 200 addresses/call). The idempotentHint=true is consistent with the stated replace-in-place semantics, and live_hazards discloses its snapshot/refresh 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?

Front-loaded with the when-to-use condition and the core action, and every clause carries information. However, it is one dense run-on paragraph with heavy parenthetical stuffing, which costs some readability for an agent parsing it.

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, 11-param creation tool with no output schema, the description covers what is produced (link, GeoJSON, KML), the return value (map_id), limits, and the update/refresh lifecycle. An agent has everything needed to call 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?

With schema coverage at 91% the baseline is 3, but the description adds real meaning: a worked bins example ('[25000, 100000] = under 25k, 25k to under 100k, 100k and over'), color_by ramp-vs-category behavior, and labels. It does not explain several top-level params (legend, flood_zones, house_districts) though the schema covers them.

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 — 'Makes a hosted map (a link anyone can open, plus GeoJSON and KML)' — and clarifies the scope (up to 20 layers, up to 2,500 pins). It also implicitly distinguishes itself from sibling answers that already show a map in the chat.

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?

'Only when the user wants a map to keep, share or change later' gives an explicit when-to-use condition, and the next clause gives the when-not ('answers with places already show a map in the chat'). It also points to update_map for later changes versus creating a new map.

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 the mutation profile (readOnly=false, idempotent=false, destructive=false); the description goes well beyond by stating the shareable link is stable and every earlier version is preserved with revert_to (so removals are recoverable despite the destructive flag being false). It also discloses that live_hazards are a snapshot frozen at render time and must be re-made to refresh, and that flood zones come from FEMA/Environment Agency and House districts use Missouri 2022 lines.

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 create-vs-edit distinction, and the trailing sentences on link stability and get_map discovery are high-value. However the long semicolon chain of capabilities is dense and hard to scan, with no grouping of the change types beyond punctuation.

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 an 11-parameter nested mutation tool with no output schema, the description covers the operation surface, versioning behaviour, discovery step via get_map, and refresh semantics for live hazards. Remaining gaps are minor: the 'legend' boolean and the exact requirement for layer creation on add_layers are left to the 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?

With 64% schema coverage across 11 params, the description meaningfully supplements the schema by explaining the pin-identification model (by id, with lat/lng or an address), the three recolour modes (single colour, by field values with per-value colours, or numeric bins in the user's own bands), and the upsert semantics of adding vs. moving pins. It leaves some params thin — notably 'legend' and 'revert_to' are not elaborated 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 opens with a precise verb+resource pair ('Change a map made with render_map') and then enumerates the concrete operation classes: add/remove layers, move/rename/add/remove pins, recolour, show/hide, rename, draw flood zones or House districts. An agent can distinguish this from render_map (creation) and delete_map 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?

It establishes the use case as editing an existing map rather than creating one, points to render_map as the source, and tells the agent to call get_map to discover layer names, pin ids and fields before issuing changes — a genuine prerequisite. It also routes version restoration to revert_to rather than a separate tool. No explicit 'do not use this for X' exclusion, which keeps it 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.

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

Beyond the annotations it discloses the key side effects and constraints: nothing is overwritten, rows are matched by id and mismatched rows are skipped and named, each write appends an audit line to an 'InstaMaps runs' tab, and the target sheet must be shared with the service account as Editor (with an error naming the address otherwise). This is consistent with idempotentHint=false (each write adds a line) and destructiveHint=false.

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?

Purpose is front-loaded in the first clause, but the second sentence is a long run-on packing run_id, job_id, mode behavior, and skip semantics into one block, which makes it harder to scan. It is dense rather than wasteful, so it stays informative.

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 6-parameter write tool with no output schema, the description covers the essentials: auth requirement, side effects, row-matching/skip behavior, mode defaults, and audit logging. Nothing critical to invoking it correctly is missing.

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 meaning: it clarifies the run_id vs job_id decision, that run_id comes from an answer (run.run_id) or get_job, and that mode/columns have defaults. It does not explain the 'tab' or 'sheet' parameters beyond what the schema already says.

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 opens with a specific verb+resource+scope: 'Writes an earlier answer into a Google Sheet without overwriting anything.' No sibling tool (ask_table, render_map, update_map, etc.) writes answer rows to a sheet, so an agent can distinguish it immediately, and the non-overwriting constraint is stated up front.

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 clear routing conditions: use run_id to write a finished answer's rows, use job_id to write chunks as a background job finishes or the whole run at completion, and it explains when each mode default applies. There are no true sibling alternatives to name, but no explicit 'when not to use' is offered.

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