ShowMeOnMap

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds behavioral details: annotations are independent of layers, have their own id namespace, and removed ids can be recycled.

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 sentences, no wasted words, front-loaded with the main action. Every sentence provides essential context.

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 no output schema and moderate complexity, the description covers the tool's core behavior, constraints, and key parameter semantics. It lacks detail on success effects or permissions but is adequate for selection.

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 83% schema coverage, the description adds value by explaining the id namespace and recycling behavior, and clarifying the rationale parameter as an audit-log label, which is not fully captured 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 clearly states the tool adds a user-placed label at a specific coordinate, distinguishing annotations from layers by noting they are independent and have their own id namespace.

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

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

The description provides context on when to use (adding standalone annotations) and explicitly states the id uniqueness constraint, though it does not directly contrast with sibling tools like 'add_layer'.

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 indicate write, non-idempotent, non-destructive. Description adds that it creates a new layer, returns correlation and counts, and allows field override. It does not specify error handling or side effects beyond return, but sufficient for agent behavior understanding.

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

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

The description is three sentences: core function, prerequisites/override, and return/required. Front-loaded with key action, no fluff or 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?

Given 8 parameters and no output schema, the description covers purpose, prerequisites, override, and return fields. Missing details like error conditions or output structure, but adequate for an agent to invoke 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 very low schema description coverage (13%), the description must compensate. It explains rationale, value_field_a/b, and required parameters. However, it fails to mention 'new_layer_id' (present in schema) and 'mode' (const bivariate), leaving ambiguity about custom ID input.

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

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

The description clearly states the tool spatially joins two layers and creates a new bivariate choropleth layer. It distinguishes from siblings like add_layer (adds an existing layer) and build_map (creates map from layers) by specifying the fusion nature.

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 mentions prerequisites ('Both layers must already exist') and advises calling build_map or add_layer first. It also notes auto-detection and override capability. However, it does not explicitly compare to alternatives or state when not to use.

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 adds valuable behavioral context beyond annotations: it explains that the tool appends without NL, describes the expected shape of the LayerPlan, and notes the rationale parameter's purpose. No contradiction with annotations (readOnlyHint=false, etc.). However, it could briefly mention the outcome of appending (e.g., layer added to workspace).

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

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

The description is three sentences, each with a clear purpose: first states the action, second provides the LayerPlan shape, third gives usage guidance and a doc reference. No waste, front-loaded with key info.

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

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

Given the parameters and lack of output schema, the description covers the purpose, usage, and parameter hints. It references external docs for the full spec, which is appropriate. Could be slightly more explicit about what happens upon success (e.g., layer added to workspace), but overall complete for an agent.

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 adds extra meaning by specifying the LayerPlan shape ('same shape the workspace pipeline emits — { id, title, source, viz, geometry, ... }') and clarifying rationale as a 'short audit-log label'. This enhances understanding beyond the schema alone.

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

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

The description clearly states the action ('Append a fully-constructed LayerPlan to an existing workspace'), specifies the resource (LayerPlan to workspace), and distinguishes it from sibling tools like mutate_map by noting it bypasses NL. The verb and target are specific and unambiguous.

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 explicitly advises when to use this tool ('when you already have a structured plan') and when to use an alternative ('otherwise use mutate_map'). It also references external documentation for the full spec, providing clear guidance for the 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 indicate a write operation (readOnlyHint=false) but not destructive. The description adds that rationale is stored in the operations log for traceability. However, it does not disclose other potential side effects, limits, or error behavior, so the added value is moderate.

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

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

The description is two sentences, starting with the core action and return value. The second sentence adds crucial guidance about not guessing shapes and referencing an external resource. Every sentence is necessary and well-placed.

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 no output schema, the description adequately explains the return (map_id) and mentions follow-up tools. It lacks details on error handling or what happens with unprocessable queries, but for a simple tool with two parameters, 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?

With 100% schema coverage, the baseline is 3. The description adds meaning by providing examples for query (e.g., 'coffee shops in Tokyo') and explaining that rationale is a required audit-log label stored for traceability. This goes beyond the schema's type/length constraints.

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

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

The description clearly states the tool's purpose: 'Create a new workspace from a natural-language query' and specifies the return value (map_id). This differentiates it from sibling tools like mutate_map or get_state, which are mentioned as follow-up actions.

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 tells when to use the tool (to create a workspace from a query) and what to do with the result (pass to mutate_map or get_state). It also directs users to a resource for downstream tool shapes, but does not explicitly state when not to use it or list 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 provide idempotentHint=true and destructiveHint=false. The description adds important behavioral context: the gated mechanism requiring confirmation, recoverability via undo, and the no-op behavior. No contradiction with 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 description is two concise sentences plus a brief note, front-loading the core action. Every sentence adds value, with no wasted words.

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

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

Given the tool's simplicity and absence of output schema, the description covers the main behavior, gating, and relationship to filter_layer. It could optionally detail the success return value, but the current content is adequate for correct usage.

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% (2 of 4 parameters have descriptions). The description does not add meaning for map_id or layerId beyond the schema, and it only echoes the schema for confirmed and rationale. It does not compensate for the 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?

The description uses specific verbs ('Wipe every predicate', 'making every source feature visible again') and clearly identifies the resource as a layer's filter chain. It distinguishes itself by stating it is the inverse of filter_layer and clarifies it is a no-op on layers with no filters.

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 explicitly contrasts with filter_layer (inverse) and notes the no-op case. It explains the gated behavior (confirmed parameter) but does not provide explicit when-not-to-use guidance beyond that.

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 and idempotentHint. The description adds valuable context: 'no layer is added, no op is committed, no credit charge' and specifies the exact return values. No contradictions.

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 concise sentences plus a required-fields note. Every sentence adds value: purpose, usage guidance, and required parameters. No filler.

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

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

Given no output schema, the description adequately describes return values and behavior. It lacks details on parameter semantics and edge cases (e.g., non-overlapping layers), but overall covers the main points.

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 17%. The description mentions the required parameters (map_id, layer_a_id, layer_b_id, rationale) but does not explain their meaning. It omits any mention of the optional parameters value_field_a and value_field_b.

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

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

The description clearly specifies the operation: spatially join two layers and return correlation statistics. It distinguishes from the sibling tool add_fusion_layer by stating when to use each (numeric answer vs visualization).

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 guidance on when to use this tool ('when you want a numeric answer without rendering') and when to use the alternative (add_fusion_layer for visualization). Also notes it's a pure read operation.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), description explains the no-server-side rendering, browser-based rendering, and download trigger mechanism. Adds valuable context about how the tool behaves.

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?

Informative with multiple sentences, each adding value. Front-loaded with purpose. Could be slightly tighter but no fluff.

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, but description clearly states return value (deep-link URL). Covers purpose, mechanism, required and optional params, defaults. Sufficient for an agent to understand and invoke 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 25% (only rationale described). Description compensates by naming required params (map_id, rationale) and defaults for optional params (format=png, legend=true). Provides meaning beyond enum values.

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

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

Clearly states it returns a deep-link URL for map export as image. Does not explicitly differentiate from sibling export tools like export_layer_data or export_workspace, but the description of user-click-driven download sets it apart implicitly.

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

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

Implies usage for exporting maps to image, specifies required parameters. Lacks explicit when-to-use or when-not-to-use guidance relative to siblings, though it notes the interactive nature (user clicks link).

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 critical behavioral details beyond annotations: download behavior via Content-Disposition, unguessable permanent URL that does not expire. No contradiction with readOnlyHint or idempotentHint.

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 sentences, front-loaded with purpose, no fluff. Each sentence adds unique value: purpose, download behavior, format details, URL durability, required parameters.

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-parameter tool with no output schema, the description covers purpose, parameter meanings, output behavior, and security. Complete enough for an agent to invoke 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 25%, the description explains the format options and rationale parameter. map_id and layer_id are self-explanatory but could be elaborated slightly. Overall adds meaning.

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

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

The description clearly states the tool exports a single layer's features as a downloadable file, with specific verb and resource. It distinguishes from sibling tools like export_image and export_workspace.

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

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

The description provides format-specific guidance (CSV drops geometry, geojson preserves it) and lists required parameters. It does not explicitly exclude alternatives but the purpose alone implies when to use.

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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds context about output shape (ops log + cursor + meta + materialized mapPlan and layerFilters) and confirms no mutation or credit charge.

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 well-structured sentences, front-loaded with purpose, no wasted words.

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

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

Given rich annotations, moderate schema coverage, and no output schema, the description sufficiently explains the return shape and usage context, making it complete for the tool's complexity.

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 has description, map_id does not). Description does not add details about parameters beyond what schema provides, so meets baseline but doesn't compensate for missing map_id 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?

Description clearly states it returns the workspace document with mapPlan and layerFilters for serialization, and explicitly distinguishes from sibling get_state.

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 provides when to use (full raw state for serialization) and when not (use get_state for compact display), and notes it's a pure read with no mutation or credit charge.

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 adds context beyond annotations: it explains the 'append' default behavior, the 'rationale' audit-log requirement, and references the Mongo-shape grammar for predicates. No contradictions with 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 description is two sentences, front-loaded with the purpose, and efficiently covers key behaviors. Slightly more structure could be added, but it's well within acceptable limits.

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 six parameters (four required) and no output schema, the description adequately covers the tool's operation. It explains the filter chain behavior, predicate grammar, and rationale requirement. No major 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?

With schema coverage at 83%, the description adds value by detailing 'append' behavior (conjunct vs replace), 'rationale' purpose (audit log), and providing predicate examples. This goes beyond the schema's property descriptions.

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

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

The description clearly states the verb 'narrow' and the resource 'layer features matching a structured predicate.' It distinguishes from siblings like 'clear_filters' or 'select_within' by specifying the structured predicate condition.

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 explains the 'append' parameter behavior (conjunct vs replace) but does not explicitly state when to use this tool over alternatives like 'select_within' or 'clear_filters'. No exclusion criteria or prerequisites are provided.

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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds no behavioral details beyond returning state. Adequate baseline given annotation coverage.

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?

Single sentence front-loaded with verb and resources. No wasted words or 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?

Simple read tool with two parameters and no output schema. Description covers the return values (workspace, map plan, filters). Lacks details on error conditions or pagination, but adequate for low complexity.

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%; only rationale is described. map_id lacks description in both schema and tool description. Description does not add meaning for map_id or clarify parameter usage 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?

Description clearly states verb 'Return' and specific resources (workspace, map plan, active filters) with required parameter map_id. Distinct from siblings like mutate_map or add_layer which write data.

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. Does not specify contexts where other read tools might be more appropriate or mention prerequisites like map existence.

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?

Description adds context about ambiguous and out-of-scope instructions, and explains the rationale parameter is for audit-logging. No annotations contradiction, but more details on response format or side effects would improve transparency.

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?

Description is concise with three sentences, each adding new information: purpose, edge cases, and documentation reference. Front-loaded with main function.

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?

Description covers purpose, valid operations, edge cases, and points to external docs. With no output schema, the description is mostly sufficient, though response structure details would increase 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?

Parameter descriptions in the schema already cover all three parameters adequately. The description adds examples for the instruction parameter and context for valid mutations, but does not significantly extend schema knowledge.

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?

Description clearly states the tool applies a natural-language instruction to an existing workspace and lists four valid mutation types. This distinguishes it from sibling tools like filter_layer or remove_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?

Description explains when to use alternatives: for unrelated instructions it emits outOfScope, suggesting to build a new map. However, it does not explicitly say when to prefer this tool over specific sibling tools for the same mutations.

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 provide readOnlyHint, destructiveHint, and idempotentHint. Description adds value by stating 'No Op is emitted and the workspace is not mutated', and notes the rationale parameter's audit-log purpose, reinforcing non-destructive behavior without contradicting 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?

Two sentences, front-loaded with the core action and complemented by a concise usage hint. Every sentence serves a purpose without waste.

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

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

Given no output schema, the description explains the basic operation and use case well. It mentions the rationale for audit logs and implies return structure. Minor gaps: no error handling details or explicit output format, but sufficient given annotations.

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 60%, and the description does not add meaning beyond the schema's parameter descriptions (e.g., limit default/max, predicate examples, rationale purpose). While schema provides adequate detail, the description does not enhance understanding of 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?

Description uses specific verb ('evaluate a predicate') and resource ('layer's inline features'), clearly stating the return of a matching subset. It distinguishes from sibling tools like filter_layer by noting it is for introspection before deciding to filter or subset.

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 no mutation and no Op emission, indicating read-only use. Provides context for introspection before filtering or building new layers, but could be more explicit about when not to use compared to siblings.

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 annotations (which are sparse), description discloses critical behavioral traits: failure instead of silent no-op when no undone ops, and truncation of redo tail upon new operations. This exceeds the minimum provided by 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?

Extremely concise: two sentences plus a note, no wasted words. Front-loaded with core action, then failure condition, then side-effect note.

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 redo operation with 2 params and no output schema, the description fully covers behavior, failure modes, and side effects, providing all necessary context 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?

Description adds no meaning to either parameter (map_id and rationale). Schema coverage is 50% (rationale described, map_id not), but the description does not compensate for unlisted details, leaving map_id's role implicit.

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?

Description uses specific verb 'Advance the workspace cursor' and resource 'the next op that was previously undone'. It clearly distinguishes from siblings like undo and mutate_map by referencing the ops log and standard edit-stack semantics.

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?

Description states when redo fails (cursor at tail) and notes that new ops after undo truncate redo tail. However, it does not explicitly compare to alternative tools like undo or apply-op, leaving the agent to infer typical usage context.

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 contradicts the idempotentHint annotation: it says removing an already-removed id fails, implying non-idempotent behavior, while annotations claim idempotentHint=true. This is a serious inconsistency. The description does add some context about id reuse, but the contradiction undermines trust.

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 sentences with no filler. The critical information is front-loaded ('Drop a previously-placed annotation by id'), followed by strictness and reuse notes. Every sentence earns its place.

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

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

For a simple tool with 3 parameters and no output schema, the description covers purpose and usage well but lacks parameter details and contradicts annotations. The return value is not described, but given no output schema, that is acceptable. However, the annotation contradiction reduces 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 description coverage is only 33% (only rationale has a description). The description does not add meaning to map_id or annotationId beyond their names. For a tool with low parameter coverage, the description fails to compensate.

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

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

The description clearly states 'Drop a previously-placed annotation by id,' specifying the verb (remove) and resource (annotation by id). It distinguishes from siblings like remove_layer by mentioning different id reuse behavior.

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 that removing an already-removed or never-placed id fails, guiding when not to use. Also explains that ids can be reused after removal, contrasting with layer ids. This provides clear usage context.

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 accurately states that removing an already-removed layer fails, which contradicts the idempotentHint=true annotation indicating the operation should have the same effect on multiple calls. This contradiction leads to a score of 1 as per rubric.

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 deliver purpose, constraints, and confirmation requirement with zero waste. Information is front-loaded and easy to parse.

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

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

The description covers the essential context: action, failure modes, tombstoning, and destructive gate. It lacks details on successful outcome or return envelope, but for a simple destructive tool with no output schema, this is nearly 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 50% with descriptions only for confirmed and rationale. The description adds no parameter-specific details beyond mentioning 'by id' for layerId, and does not explain map_id. For a low-coverage scenario, the description fails to compensate.

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 'Drop a layer from the workspace by id' clearly states the action and resource. The title also reinforces purpose. Among sibling tools, there is no other layer removal tool, so it is unambiguous.

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

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

The description provides clear context on when to use (to remove a layer) and important constraints: failure if already removed or never-added, and the need for confirmation. It does not compare with alternatives, but no direct alternative exists, so it is sufficient.

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 adds behavioral details beyond annotations: it explains that the operation re-keys filter chains, preserves insertion order, and enforces uniqueness constraints (including tombstoned ids). Annotations provide idempotentHint=true but the description adds context about side effects.

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

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

The description is three sentences, front-loaded with the primary action. Every sentence provides essential information without redundancy, making it concise and efficient.

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?

Without an output schema, the description does not explain the return format or success indicators. However, for a rename operation, the return is likely minimal. The description covers key constraints and side effects, but could mention expected response or error conditions.

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% (newLayerId and rationale have descriptions in schema). The description clarifies the purpose of oldLayerId and newLayerId ('from oldLayerId to newLayerId') and reinforces the uniqueness requirement, adding meaning beyond the schema for these 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?

The description clearly states the action ('Change a layer's id from oldLayerId to newLayerId'), specifying the verb (rename) and resource (layer id). It distinguishes this tool from siblings like add_layer or remove_layer by focusing on renaming identifiers.

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 does not provide guidance on when to use this tool versus alternatives. It lacks context like prerequisites or conditions where renaming is appropriate, and does not mention when not to use it.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds that it records to a server-side log and does not unblock the session. This provides useful context beyond annotations, but annotations already cover safety profile.

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 sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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 no output schema, description explains what happens (logging, no unblock). Covers optional map_id and all required params. Could mention return value, but for a feedback tool this is sufficient.

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 schema already documents each parameter. Description does not add parameter-specific details beyond schema. Baseline score of 3 is appropriate.

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

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

Description clearly states the tool's purpose: reporting blockers encountered by the agent. It uses a specific verb ('Tell') and resource ('ShowMeOnMap team'), and distinguishes from sibling tools by referencing build_map, mutate_map, and direct-op tools.

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

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

Explicit guidance on when to use: when build_map/mutate_map/direct-op tool returns unrecoverable error or when a different tool would be desired. Also states what it does not do (does not unblock current session) and that no map_id is required.

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 adds behavioral context beyond annotations: it discloses that unsupported fields are silently ignored (a potential surprise) and that a no-input call is a no-op (idempotent). Annotations already mark idempotentHint=true, so this reinforces that. No contradictions. Missing details on side effects or permissions, but acceptable given the tool's simplicity.

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

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

The description is just two sentences with no extraneous information. Every word serves a purpose: the first sentence states the action, the second clarifies constraints and edge cases. Excellent conciseness.

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

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

Given the tool's low complexity (5 parameters, no nested objects, no output schema), the description covers the key behaviors: what it does, constraints, and accepted inputs. It omits return value or error behavior, but for a simple mutation tool, this is sufficient. The annotation coverage (idempotent, non-destructive) complements the description.

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, opacity, rationale have descriptions; map_id and layerId do not). The description adds overall parameter behavior (at least one of color/opacity required, no-op if neither) which is not in the schema. However, it does not elaborate on the undocumented parameters, so it partially compensates.

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

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

The description clearly states the tool adjusts a layer's color and/or opacity, using specific verbs and resource. It distinguishes itself from sibling tools by explicitly noting 'within-palette changes only,' implying it does not add new layers or modify other properties. This makes its purpose unambiguous.

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

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

The description provides clear guidance: pass at least one of color/opacity, and notes that passing neither is an accepted no-op. It also warns about the renderer silently ignoring unsupported fields, which helps prevent misuse. However, it does not explicitly mention when to use alternatives among sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the source layer is untouched and a new layer is created, confirming the non-destructive behavior. No contradictions with 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 description is two sentences long—the first conveys the core functionality, the second provides a usage example. No redundant words or information. Every sentence adds value.

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

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

Given the tool's simplicity, the annotations cover safety, and the schema documents parameters, the description is sufficient. It does not mention that the new layer will be added to the map, but that is implied by 'Create a new layer'. Lacks a minor detail but otherwise 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 description coverage is 67%, with selection and newLayerId already documented. The description mentions 'within the supplied polygon', which ties to the selection parameter, but does not elaborate on map_id or sourceLayerId. The added value beyond the schema is marginal.

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

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

The description clearly states the verb ('Create'), the resource ('new layer'), and the specific operation ('features within supplied polygon'). It also provides a concrete use case ('show me only the X inside this country/bbox/hand-drawn shape'), which distinguishes it from sibling tools like filter_layer (attribute-based filtering).

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 explicitly says when to use the tool ('show me only the X inside...'), providing a clear context. It does not explicitly mention when not to use it or list alternatives, but the use case differentiation is clear enough for an agent to select appropriately.

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 indicate idempotentHint=true. Description adds 'Latest set_camera op wins during replay' and equivalence to mutate_map's camera move, providing useful behavioral context beyond 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?

Description is concise, front-loaded with purpose, and every sentence adds value. No unnecessary words or 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?

Given the tool's complexity (two modes, no output schema), the description covers usage, behavior, and parameter semantics thoroughly. Annotations provide additional safety context, making it complete for agent selection.

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 33% but description compensates by explaining the two parameter groups (fitBounds with bbox, flyTo with center/zoom) and optional fields, clarifying the structure that schema's oneOf represents.

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?

Description clearly states 'Override the workspace camera' and explains two distinct modes (fitBounds and flyTo) with specific use cases. Differentiates from sibling mutate_map by highlighting it skips NL roundtrip.

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 recommends when to use: 'zoom to Japan', 'center on Paris at z=10', or finishing drill-down after filter_layer. Also contrasts with mutate_map. Lacks explicit when-not-to-use, but context implies direct camera control.

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 (idempotentHint=true, destructiveHint=false), the description explains replay behavior ('Latest set_time op wins'), current consumption status, and that the value is queryable via get_state, adding significant transparency.

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

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

The description is extremely concise: three sentences that front-load the core action, then add key behavioral notes with zero wasted words.

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

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

For a tool with 6 parameters and no output schema, the description covers purpose, usage, replay behavior, and current limitations. It could mention edge cases or error handling, but 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 description coverage is high (83%), so the schema already documents most parameters well. The tool description does not add new parameter-level details beyond implying the use of rangeStart and rangeEnd for time bounds.

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

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

The description clearly states the tool overrides the time-range filter, provides concrete example intents ('filter to 2020-2024', 'show only the last 7 days'), and implicitly distinguishes it from sibling filter tools by focusing on time windows.

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 explicitly lists appropriate use cases with examples, but does not mention when not to use it or compare to sibling tools like filter_layer. The caveat about not being consumed by the renderer provides helpful context.

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 claims idempotence for same labels, but annotations set 'idempotentHint' to false. This is a direct contradiction. The description also mentions mirroring into workspace.meta.tags, but the safety profile is inconsistent.

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 concise sentences with no waste. First states purpose, second adds UI detail, third clarifies idempotency. Front-loaded efficiently.

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

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

The description covers the operation's effect and side-effect (mirroring) but does not describe the return value or error handling. Given no output schema, more context on response would be helpful. The contradiction also undermines reliability.

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 67% schema description coverage, the description adds meaning for 'name' and 'rationale' (audit-log purpose) but not for 'map_id'. The mention of 'current workspace' helps contextualize map_id, but schema already covers it minimally.

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

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

The description clearly identifies the tool's purpose: labeling the current workspace state with a user-supplied name and mirroring it for UI history. It is distinct from siblings like 'add_annotation' or 'build_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?

The description does not provide guidance on when to use this tool vs. alternatives, such as when to tag vs. add an annotation. No explicit when-not-to-use information.

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 mark readOnlyHint and destructiveHint as false, which the description complements by explaining that undo does not delete ops but re-materializes state. It also discloses the gating behavior and the autonomous footgun warning. This adds value beyond the annotations without 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?

The description is concise (three sentences) and front-loaded with the core purpose. It efficiently covers behavior, edge cases, gating, and interaction with redo without extraneous words. Every sentence earns its place.

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

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

Given the tool's complexity (gated undo, redo interaction, genesis case), the description covers the key behavioral aspects. It does not include return value details, but there is no output schema, so that is acceptable. The description is complete enough for an agent to invoke correctly.

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

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

The schema covers 67% of parameters; the description adds meaning for 'confirmed' (gating, returns needs_confirmation envelope) and 'rationale' (audit-log label, traceability). It does not explain 'map_id', but that is standard. The added context justifies a score above 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?

The description clearly specifies the verb 'Rewind the workspace cursor' and the resource 'state before the last mutation'. It distinguishes from sibling 'redo' by stating 'Does NOT delete any ops — redo will fast-forward', and explains the genesis edge case. This leaves no ambiguity about what the tool does.

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 explains when to use (to undo the last mutation) and when not to (at genesis, returns error). It provides explicit guidance on the gated nature: 'pass confirmed:true to proceed'. However, it does not directly contrast with sibling mutation tools like mutate_map, but the context is sufficient.

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