ShowMeOnMap

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: annotations are layer-independent, use a separate id namespace, and the id must be unique among CURRENTLY-placed annotations with removed ids recyclable. It stops short of stating the failure mode when the id is in use.

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 short sentences, front-loaded with the core action, then namespace scope, then the uniqueness constraint. No filler, though the terse 'Strict:' lead-in reads slightly clipped rather than polished.

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-param, non-read-only tool with no output schema, the description covers the key ambiguities: what an annotation is, that it is layer-independent, and the id collision rule. It does not state the error behavior on a duplicate id or how the call is acknowledged, 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 description coverage is 83%, so the schema already documents id ('Stable id'), coords ([lng, lat] WGS84), color and rationale. The description meaningfully extends the id parameter by explaining the namespace and strict uniqueness rule, which the schema does not state, adding real value over the structured fields.

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 ('Add a user-placed label at a specific coordinate') and clarifies scope by noting annotations are 'independent of layers' and live in their own id namespace, which separates it from add_layer/add_fusion_layer. It never explicitly names a sibling tool (e.g. remove_annotation) as a contrast, so it falls just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is for placing a free-standing marker rather than a layer, but there is no explicit when-to-use, when-not-to-use, or named alternative. The id-uniqueness statement is an operational constraint, not selection guidance.

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 declare idempotentHint=true and destructiveHint=false, and the description adds real context beyond them: the confirmation gate (pass confirmed:true or receive a needs_confirmation envelope) and the no-op behavior on unfiltered layers. It does not describe the return shape, but the gating and idempotency/no-op disclosure is meaningful added value.

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 tight sentences, each earning its place: operation+scope first, sibling relationship second, edge case and gate last. No filler or restatement of the name.

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?

Mutable tool with no output schema; the description covers the gate, the no-op case, and the inverse relationship, and the schema's confirmed description notes undo restorability. An agent has what it needs to invoke correctly, though the return envelope details beyond needs_confirmation are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%: confirmed and rationale are documented in the schema, while map_id and layerId are bare. The description reinforces the confirmed gate ('pass confirmed:true to proceed'), adding meaning for the most consequential parameter, but it does not clarify the two required identifier params, so it only partially compensates for the coverage gap.

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 ('wipe every predicate... on a layer's filter chain') and the resulting state ('making every source feature visible again'), then explicitly positions itself as the 'Inverse of filter_layer.' An agent can distinguish it from the sibling filter_layer 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?

Names the inverse operation (filter_layer) and clarifies the no-op case ('No-op on layers that have no existing filter'), which tells the agent when a call is redundant. It doesn't state a hard when-not-to-use condition beyond the no-op, so it falls short of explicit alternatives/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 declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is partly covered. The description adds real behavioral value beyond that by stating the append default and that append:false 'replaces the chain' — disclosing what existing state is overwritten. It stops short of permission/reversibility notes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, fully front-loaded: the core action first, then the append/replace distinction. No filler, every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with annotations covering the safety profile and a high-coverage schema handling parameters and the nested predicate grammar, the description supplies enough to invoke correctly. Missing only edge context such as permissions or interaction with undo/clear_filters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema already documents append, intent, predicate, and rationale in detail. The description only reinforces append behavior, which the schema already explains, adding little beyond the structured fields. Baseline 3 is appropriate when the schema carries the load.

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: 'narrow a layer to features matching a structured predicate.' An agent can tell this apart from clear_filters and query_features by the 'narrow a layer' framing. However, it never names an alternative sibling directly, so differentiation is inferred rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'narrow a layer' but there is no explicit when-to-use/when-not or pointer to alternatives like clear_filters (to remove) or select_within/query_features. The append semantics hint at the additive-vs-replace decision but don't frame it as tool selection guidance.

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?

Adds substantial context beyond annotations: emits undoable ops (filter / new layer + camera), produces a grounded summary, costs 1 credit on successful mutation, and refunds clarifications. Clarifies that failure returns candidate names rather than guessed geometry. Annotations already cover safety, but this enriches the operational picture.

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 tightly written sentences, front-loaded with the purpose and key constraint, then behavior, then cost. Every sentence adds distinct value with no repetition.

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 tool with no output schema, the description covers purpose, key parameter semantics, error handling, reversibility, cost, and output format. The only minor gap is not restating mode option differences, which the schema already documents.

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 40%, so the description must compensate. It explains the core areaRef parameter well (three kinds, names not coordinates, examples) but does not cover mode options, bufferMeters, radiusMeters, or map_id/layerId semantics beyond the schema. Partial compensation.

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 (refine), resource (layer), and scope (named area resolved from OSM), with examples and a clear boundary: names only, never coordinates. This distinguishes it from coordinate-based siblings like select_within, though no sibling is named explicitly.

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 a hard usage rule ('Pass names only, never coordinates') and explains behavior for unresolvable names, which frames when the tool applies. However, it does not name alternative sibling tools or explicitly state when to choose this over filter_layer or select_within.

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 idempotentHint=true, so the safety profile is covered. The description adds little beyond stating it's a load operation for a viewer card, but that context ('viewer only', 'Not for the model') is mildly useful. It doesn't describe pagination (cursor), layer filtering effects, or behavior on missing map_id.

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?

Very brief, two short sentences, front-loaded with the core purpose. However, the 'Not for the model' sentence is arguably wasted space that doesn't help an agent select or invoke the tool correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given four parameters at 0% schema description coverage and no output schema, the description is far too thin. It fails to explain parameter meaning, return shape, or how this differs from other viewer/state tools, leaving significant gaps for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description says nothing about any of the four parameters (map_id, op_id, cursor, layer_ids). With no compensation in the description, an agent has no semantic guidance for these undocumented parameters.

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 general purpose (load a map version) but is vague on what 'map view' actually returns and how it differs from siblings like get_state or build_map. The odd note 'Not for the model' is more of a routing directive than a purpose statement, leaving the actual scope unclear.

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?

No guidance on when to use this tool versus alternatives like get_state or build_map. The phrase 'Used by the ShowMeOnMap map card' implies a specific client context but does not translate into actionable when/when-not guidance for an agent.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description usefully adds what the read returns (workspace, plan, active filters), but says nothing about whether the read is scoped, truncated, or requires the map to exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the verb and the returned content, with zero filler. Nothing could be removed without losing 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 simple read-only getter with no output schema, the description enumerates the three returned elements, which is exactly the information the agent would otherwise lack. Only the semantics of map_id remain 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?

Schema description coverage is 50%: 'rationale' is documented in the schema, but 'map_id' has no description there and the description only says 'for a given map_id', adding no format, origin, or constraint information. It does not compensate for the coverage gap on the required parameter.

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 ('Return') and enumerates the returned resources (workspace, map plan, active filters), which is more concrete than the title 'Read map state'. It is distinguishable from siblings like export_workspace or list_workflows, though it never names an alternative to disambiguate.

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?

No when-to-use guidance, no prerequisites, and no mention of when a sibling (e.g. export_workspace, list_workflows) would be preferable. The agent must infer usage entirely from the purpose sentence.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful scope and return content ('caller's saved workflows', 'parameters and per-run credit estimates'), but does not address pagination, rate limits, or auth requirements.

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 front-loaded sentence with no filler. Every element — verb, scope, returned data — earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with no output schema, the description tells the agent what it returns ('parameters and per-run credit estimates') and who scopes it ('caller's saved'). Missing pagination or limit behavior is a minor gap for this complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single optional rationale parameter, so the schema carries the parameter meaning. The description adds no extra parameter semantics beyond what is already documented.

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 (list saved workflows) and adds the returned data shape (parameters and per-run credit estimates). This clearly separates it from run_workflow and save_workflow without needing schema inspection.

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 implied by the purpose: an agent should call this when it needs to inspect saved workflows. However, it does not explicitly say when to choose this over run_workflow or save_workflow, leaving alternative 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 declare non-read-only, non-idempotent, open-world behavior; the description adds genuinely new context by disclosing the two special response states (clarification, outOfScope) that an agent must handle. It omits whether removed layers are recoverable or whether edits are undoable, which matters for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with the core action, then valid mutations, then the two exceptional response paths, then the doc pointer. No filler or restatement of the tool name.

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 scope, ambiguity handling, out-of-scope routing, and defers the Op grammar to a named resource, which is complete for a natural-language mutation entry point. No output schema exists, so return shape relies on the description, which only partially names the emitted fields (clarification, outOfScope) rather than the full success 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 100% and all three parameters (map_id, instruction, rationale) are documented in the schema with examples and constraints. The description adds no parameter-level syntax or format guidance beyond what the schema already provides, so baseline 3 applies.

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 ('Apply a natural-language instruction to an existing workspace') and enumerates the exact mutation scope (filter/remove layer, camera, basemap). This distinguishes it from atomic siblings such as filter_layer, remove_layer, and set_camera, which do the same work one operation at a time.

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 routing rules: ambiguous instructions yield a clarification field, unrelated instructions yield outOfScope and the agent should 'build a new map in that case', naming the alternative sibling. It also points to the resource documenting the full Op catalog and predicate grammar.

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 non-open-world, so the safety profile is covered. The description reinforces this and adds a valuable app-specific trait: no Op is emitted and the workspace is not mutated, which matters in this ops-log model. It doesn't cover pagination/return-shape behavior beyond the schema's truncation note.

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 tight sentences, front-loaded with the core action and scope, then the read-only guarantee, then the use case. Every sentence earns its place with no redundant restatement of the name or schema.

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 notes it returns the matching subset and the schema exposes the limit/truncated contract, so an agent has enough to invoke it. It could say more about the return shape (fields, ordering), but for a read-only query with rich annotations it is largely 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?

Schema coverage is 60%: limit and predicate are well documented (the predicate grammar and examples live in the schema), while map_id and layerId are bare strings. The description alludes to evaluating a predicate but adds no syntax, format, or per-parameter meaning beyond what the schema already provides, so the baseline of 3 fits.

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 (evaluate a predicate) and resource (a layer's inline features) plus the result (the matching subset), which is unambiguous. It lightly frames itself against filtering/subsetting/new-layer siblings, though it never names the concrete alternative like filter_layer. An agent can tell what it does but must infer the contrast from the context.

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?

Clearly positions the tool as introspection ("how many X match Y?") to run before deciding to filter, subset, or build a new layer. That gives concrete when-to-use context absent from the schema. It stops short of explicit when-not or naming the sibling to use instead, so it's not a full 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?

Annotations declare non-readonly, non-idempotent, non-destructive, and the description adds two behavioral facts those hints don't convey: failure instead of silent no-op at the tail, and redo-tail truncation when a new op is applied after an undo. It stops short of describing what the replayed op returns or how state changes are surfaced, so it's strong but not exhaustive.

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 action and followed by the failure mode and the truncation caveat; each sentence carries distinct information. The 'Note:' framing is slightly ceremonial but the content is not padding.

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 purpose, failure behavior, and the stack-truncation side effect for a small two-param mutation tool with no output schema. The one real gap is return behavior (what the replayed op yields / resulting cursor state), which no structured field documents and the description omits.

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 50%: `rationale` is fully documented in the schema, while `map_id` carries no description in either place. The description never clarifies map_id's role or how it relates to the cursor/ops-log model, so it adds little semantic value over the structured fields.

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 mechanism ('advance the workspace cursor by one toward the tail of the ops log, replaying the next op that was previously undone'). This is immediately distinguishable from the sibling `undo`, which moves the opposite direction, so an agent can select correctly 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 clear usage context: call it to re-apply an undone op, and it fails when the cursor is already at the tail. The counterpart tool (`undo`) is implied by 'previously undone' but never named explicitly, so the when-to-use-vs-alternative routing is clear-but-not-explicit rather than fully spelled out.

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 supply the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), but the description adds genuinely valuable behavior beyond them: strict failure on non-existent ids and the id-reuse lifecycle contrasted with session-tombstoned layer ids. It omits permission/auth requirements and any return/confirmation behavior, keeping it short of a 5. Note there is mild tension between the 'removing an already-removed id fails' strictness and idempotentHint=true, though the second call still leaves state unchanged, so it is not a true contradiction.

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 tight sentences with the core action front-loaded, followed by failure semantics and the id-lifecycle caveat. No filler and no repetition of the title 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 simple mutation tool with no output schema and no nested objects, the description covers the action, error behavior, and a cross-tool lifecycle distinction, which is close to sufficient. It stops short of stating permissions, whether the removal is undoable, or what a successful call returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33%: only 'rationale' is documented in the schema. The description clarifies that the target is the annotation id ('by id'), which maps to annotationId, but says nothing about map_id or the rationale/history-label parameter. It adds modest value over the parameter names alone rather than compensating for the coverage gap.

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 ('Drop a previously-placed annotation by id'), making it unmistakably distinct from the sibling add_annotation and from layer-oriented tools like remove_layer. An agent can select it 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?

The description implies the only valid usage (removing a previously-placed annotation id) and states the failure condition for already-removed or never-placed ids, which is useful context. However, it never contrasts this tool with alternatives such as remove_layer or mutate_map, nor does it state prerequisites like map selection, so routing guidance is only partial.

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=true and idempotentHint=true, but the description adds substantial non-redundant behavior: strict failure on already-removed/never-added layers, tombstoning of ids so they cannot be re-added, and the gated confirmation protocol. This is exactly the extra context structured annotations cannot convey.

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 the core action then strictness, the id-tombstone caveat, and the confirmation gate. No filler; each clause carries actionable 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 gated destructive tool with no output schema, the description covers the confirmation envelope, failure modes, and immutability of removed ids. It stops short of clarifying what map_id/workspace actually refers to, leaving a small gap given the 50% schema coverage.

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 50%: confirmed and rationale are documented in the schema, while map_id and layerId are not. The description reinforces the workspace/id scoping and the confirmed gating but adds little new syntax or format detail beyond the schema, so a baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Drop a layer from the workspace by id" states a specific verb (drop/remove) and resource (layer) with scope (by id). It is trivially distinguishable from siblings like add_layer, rename_layer, or remove_annotation, and the strictness/tombstone semantics sharpen the purpose further.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear precondition for invocation (must pass confirmed:true, otherwise a needs_confirmation envelope) and states the failure conditions. It does not, however, mention any alternative route such as undo_/redo to reverse a removal, so it stops just short of full when/when-not/alternatives guidance.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses real side effects: the existing filter chain is re-keyed, sibling insertion order is preserved, uniqueness is enforced against both live and tombstoned ids, and later operations must use the new id. That is exactly the behavioral context the annotations cannot convey.

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 tight sentences, zero filler, and the core action is front-loaded ahead of the side effects and constraints. Every clause contributes operational information an agent needs before calling.

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 four-parameter mutating tool with no output schema, the description covers the action, side effects, uniqueness precondition, and follow-on id requirement. It leaves the optional rationale parameter and failure-mode behavior unaddressed, but nothing essential for a correct call 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 50%, so the description must carry weight, and it does for the two critical parameters: it defines the old/new id relationship and extends the schema's 'unique within the workspace' note with the crucial 'current OR tombstoned' qualification. map_id and rationale receive no description-level treatment, but the added precision on the re-keying params goes 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?

The description states a specific verb and resource ('Change a layer's id from oldLayerId to newLayerId') and immediately scopes it with the exact inputs involved. It is trivially distinguishable from siblings like add_layer, remove_layer, and restyle_layer, which operate on different aspects of a layer.

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 implied rather than stated: the 'Strict: newLayerId must not already be in use (current OR tombstoned)' line gives a precondition that steers correct invocation, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., remove_layer + add_layer). An agent can infer the context but is not routed.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the mutability profile is covered. The description adds genuinely useful behavioral detail beyond them: the renderer 'silently ignores fields the current viz variant doesn't support' and a no-op is accepted, which the agent could not infer from structured fields.

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 tight sentences, front-loaded with the core action before the caveats. The scope constraint and no-op behavior are stated in the fewest words possible, and nothing is repetitive.

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 tool with no output schema, the description adequately conveys what changes, the scope limit, and the no-op edge case, and annotations carry the safety profile. The only gap is that the required map_id/layerId parameters are never explained anywhere.

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%; color and opacity are documented in the schema with format/range, and the description adds the constraint that at least one is required and that unsupported ones are silently dropped. However, the two required identifiers (map_id, layerId) have no description text in either the schema or the description.

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 ('Adjust a layer's color and/or opacity'), which inherently separates it from siblings like rename_layer or filter_layer. It never names an alternative explicitly, so the differentiation is achieved through specificity rather than routing.

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 clear usage constraints: 'within-palette changes only' and 'Pass at least one of color / opacity; passing neither is an accepted no-op.' This tells the agent the operational envelope, but no alternative sibling (e.g. a deeper mutate/restyle tool) is named for cases outside the palette.

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

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

With annotations only declaring readOnly=false/idempotent=false/destructive=false, the description carries the real behavioral load: the result REPLACES its input layer(s) (undoable), 1 credit charged only when the result lands, typed failures (unknown layer, too few features, >10,000-feature cap) refunded, null-vs-zero guarantees, and a grounded memo whose numbers are 'computed, never generated.' The replacement semantics sit in mild tension with destructiveHint=false, but the explicit '(undoable)' qualifier resolves it rather than contradicting the annotation.

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 and its replacement semantics are front-loaded well, but the bulk of the text is a semicolon-chained enumeration of the seven modes that closely duplicates the schema's own `analysis` enum description, so a meaningful share of the length is redundant with structured data.

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 24-parameter tool with no output schema, the description covers everything an agent needs: return shape ('grounded memo + stats payload'), credit and refund behavior, failure modes, input-replacement semantics, and per-mode data-handling guarantees.

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 96%, so per-parameter syntax is already documented and the baseline is 3; the description still adds meaning the schema does not, e.g. that omitting valueField on a point layer switches hotspot into hex density mode, that unmatched enrich/join features stay null rather than zero-filled, and that merge/dissolve never null-fill schemas.

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 clause gives a precise verb+resource+effect: 'Compute a spatial analysis server-side and append the finished... result as a new layer + camera,' and the per-mode breakdown (hotspot/zonal/enrich/join/merge/near/dissolve) makes the scope unambiguous. It never differentiates itself from related siblings such as correlate_layers or select_within, which also operate on layers, so it falls short of the 5 bar for sibling differentiation.

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?

Offers strong mode-selection routing, most notably 'the aggregate direction (points INTO polygons) is zonal' to disambiguate join vs zonal, plus concrete tips like 'filter first or use state for wider layers' and cost/refund conditions. It gives no guidance on when to reach for a sibling tool instead of this one, so context is clear but exclusions are absent.

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?

Adds substantial behavior beyond the annotations (readOnly=false, destructive=false, idempotent=false): billing (~1 credit/step, batch bills steps × values), clarification pauses a single run with status "paused", failures stop at the failing step while batch continues per value, and the success result is a live map with a shareable URL. These are exactly the operational traits an agent cannot infer from 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?

Purpose is front-loaded and every sentence carries operational weight (billing, batch, pause, failure, return). It is dense and slightly packed into one paragraph, but there is little redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param tool with a nested batch object and no output schema, the description is thorough: it documents billing, batch semantics, failure/pause handling, and the returned live map/URL. It omits auth/permission requirements and how to resume a paused run, leaving minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description's batch explanation (sweep ONE param, 2-20 values, each a full run) largely restates what the schema's batch.param and batch.values descriptions already state, adding only marginal detail.

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 ("Execute a saved workflow with parameter values") and names list_workflows as the source of the cost estimate, clearly separating it from save_workflow/list_workflows. An agent immediately knows this runs an existing workflow rather than creating or enumerating one.

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 clear operating context: batch mode is for sweeping ONE declared param across 2-20 values, and the estimate lives in list_workflows. It does not, however, explicitly contrast run_workflow with build_map/mutate_map or state when-not to use it, so it falls short of a full when/when-not/alternatives 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 declare a non-readonly, non-idempotent, non-destructive write, but the description adds substantive behavior the annotations cannot: later runs re-execute against FRESH data and bill per step like a normal typed action. That cost/freshness disclosure is genuinely useful. It stops short of stating whether saving is versioned or overwritten.

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 dense sentences, each carrying distinct information (what it is, how to parameterize, what running it later does), with the core concept front-loaded and zero 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 creation tool with no output schema, the description covers the essential semantics and even anticipates the downstream run behavior. It does not say what the save returns (e.g., a workflow id needed for run_workflow), which is the one meaningful 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 schema descriptions already explain steps, params, and the brace-slot convention, so the description largely restates them. It reinforces the ordering rule (step 1 builds, later steps mutate) but adds no syntax or constraint not already 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 (save a workflow) and defines what the resource actually is: an ordered list of NL instructions, parameterized, re-runnable. This clearly separates it from list_workflows (read) and run_workflow (execute), which are the ambiguous siblings.

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 conveys the intent (capture a parameterized sequence so it can be re-run later) and implies the counterpart tool, run_workflow. It does not explicitly name alternatives or state when-not to save, but the surrounding context makes the choice clear.

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?

The description states the tool 'Create[s] a new layer' (a state-mutating operation on the workspace), yet the annotations declare readOnlyHint=true. This is a direct contradiction of the same kind as the create_record calibration case, so the behavioral signal given to the agent is unreliable. The useful extra detail ('source layer is untouched') cannot offset a safety-hint conflict.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first states the operation and the non-destructive guarantee, the second gives a concrete usage idiom. Nothing is padded and the key constraint is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter, nested-object tool with no output schema, the description adequately conveys the outcome (a new layer, source unchanged). It does not address error surfaces (e.g. duplicate newLayerId, invalid geometry) or what the call returns, but the core call semantics are covered.

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 67%: map_id, sourceLayerId and rationale are documented in the schema, and selection/newLayerId/inheritStyle carry inline schema descriptions. The prose adds the spatial semantics ('features that lie within the supplied polygon') but no detail about inheritStyle or the required IDs beyond what the schema already states. Baseline 3 for moderate coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and output ('Create a new layer containing the source layer's features that lie within the supplied polygon') and clarifies the source layer is untouched. It distinguishes the operation from a plain add_layer by defining the spatial-subset semantics, though it never names the closest sibling (filter_layer) explicitly.

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 offers a use-case cue ('show me only the X inside this country/bbox/hand-drawn shape'), which implies when the tool is appropriate. However, there are no explicit when-not conditions or named alternatives such as filter_layer or add_layer, so the agent must infer the 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?

Adds behavior beyond annotations: it discloses the override semantics and replay determinism ("Latest set_camera op wins during replay"), which matters for an idempotentHint=true, destructiveHint=false mutation. It does not describe the response or failure behavior, but for an idempotent camera op the disclosed constraints are the meaningful ones.

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, all front-loaded with the core purpose first, then modes, then the mutate_map relationship. Dense but every clause carries distinct information; only the trailing "Covers requests like..." sentence is mildly redundant with the mode enumeration.

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 3-param mutation with no output schema, the description supplies the mode structure, override/replay semantics, and the sibling relationship. An agent can invoke it correctly. The missing piece is any mention of the rationale field's map-edit-history role.

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 only 33% schema coverage, the description compensates well by spelling out each mode's fields: fitBounds takes [w,s,e,n] bbox plus optional padding/animateMs; flyTo takes [lng,lat] center + zoom plus optional pitch/bearing/animateMs. It does not explain the rationale parameter's history-log purpose, but it covers the two hard-to-infer discriminated branches.

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 ("Override the workspace camera") and immediately enumerates the two supported modes, so an agent knows exactly what the tool does. It also names the sibling it makes redundant (mutate_map's camera move), which is rare and valuable differentiation.

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 states the direct-usage case and the alternative: "Equivalent to the camera move mutate_map would emit, but skips the NL roundtrip," plus concrete request examples ("zoom to Japan", "center on Paris at z=10"). It stops short of stating when a direct camera set is inappropriate (e.g. when a full NL edit is wanted), but the routing context is clear.

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 genuinely non-obvious behavior: the value is not yet consumed by the renderer and instead lands in the ops log where it is retrievable via get_state. That is materially useful state-effecting context the readOnly/destructive/idempotent hints cannot convey.

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 short sentences, front-loaded with the core action and followed by ordering semantics and the renderer caveat. Every sentence carries distinct information with no padding.

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 tool with no output schema, the description covers the core action, overwrite/replay semantics, and where the value ends up. The main omission is any explicit routing against alternative filter tools.

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 83%, so the schema already documents field, rangeStart/rangeEnd, format, and rationale in detail. The description only alludes to the time range generically and adds no syntax or format guidance beyond what the schema provides, so the baseline 3 applies.

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+resource: 'Override the current time-range filter,' matching the title's 'set the time window.' It is clearly distinct from neighboring tools like clear_filters or query_features, though it never names a sibling directly to sharpen that contrast.

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 trigger phrases ('filter to 2020-2024', 'show only the last 7 days') and a replay-ordering rule ('latest set_time op wins'), which is real usage context. However it gives no when-not guidance and never contrasts against clear_filters or filter_layer, so the agent must infer the 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?

The description asserts 'Tagging the same label twice is idempotent — no error, no duplicate entry,' but the annotation explicitly declares idempotentHint=false. This directly contradicts the structured metadata and could cause an agent to make a wrong assumption about repeat-call 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 action and effect, with no filler. The only weakness is the final sentence, which introduces the contradiction rather than useful clarity.

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 tool (readOnlyHint=false) with no output schema, the description adequately covers the write effect and the meta.tags mirroring. However, it omits permission/prerequisite context and the incorrect idempotency claim undercuts completeness.

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 67%, above the baseline threshold, and the schema already documents both 'name' and 'rationale'. The description reinforces that 'name' is user-supplied and reveals the meta.tags storage side effect, but says nothing about 'map_id' (undocumented in the schema) or the rationale parameter.

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 (label) and resource (current workspace state) and explains the concrete effect (mirrored into workspace.meta.tags). It is clear what the tool produces, though it does not explicitly distinguish itself from the similarly-named sibling add_annotation, which could cause selection confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this over alternatives like add_annotation, save_workflow, or build_map, nor any stated prerequisites. The idempotency note is behavioral, not a usage rule.

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?

Adds substantial context beyond the annotations: it discloses that no ops are deleted (aligning with destructiveHint=false), that redo can restore state, and that the gated path returns a needs_confirmation envelope rather than performing the action. The genesis no-op-that-errors behavior is a genuinely useful disclosure no annotation conveys.

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 tight sentences, front-loaded with the core action before the edge case and gating details. Slightly redundant with the schema's own description of the confirmed parameter, but no wasted phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so by describing the needs_confirmation envelope. It covers the primary failure mode (genesis) and gating, though it omits the optional rationale label behavior.

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 67% and the schema already describes confirmed and rationale in detail. The description restates the confirmed gating semantics but adds nothing about the undocumented map_id or the rationale label, so it does not materially exceed the schema baseline.

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 ('Rewind the workspace cursor by one') with a precise scope constraint ('the most recent op'). It explicitly names the sibling relationship ('redo will fast-forward'), letting an agent distinguish undo from redo without inspecting 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?

Explains the genesis edge case (cursor === 0 is a no-op that errors) and the gating condition (pass confirmed:true or get a needs_confirmation envelope). It does not fully spell out when to prefer undo over redo, but the contrast sentence gives clear routing context.

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