Handled Locator

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

Annotations already declare destructiveHint=true, so the agent knows this is a mutating operation. The description adds valuable behavioral context beyond that: it states the tool will be 'Refused if the locator changed since the proposal was prepared,' which is a runtime failure condition the agent needs to know. It also implies a stateful workflow (proposal must exist and be agreed upon). It doesn't detail the exact side effects of making the proposal live, but the destructive annotation plus the refusal condition provide solid 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?

Three sentences, each earning its place: the first states the action, the second gives the critical usage precondition, the third warns about a failure condition. It is front-loaded with the core purpose and contains zero filler. This is an exemplary concise definition.

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 single-parameter tool with a clear destructive annotation and a well-described workflow, the description is nearly complete. It covers the purpose, the prerequisite, and a key failure condition. The only minor gap is that it doesn't describe what the response looks like or what 'making live' concretely changes on the website, but with no output schema and a simple parameter set, the description provides enough for an agent to call it correctly.

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

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

Schema description coverage is 100% – the single parameter proposalId is fully described in the schema as 'The id returned by propose_configuration.' The description adds the context that this id comes from a prepared proposal and that applying it is the action, but it doesn't add new parameter-level meaning beyond the schema. Baseline 3 is appropriate since the schema carries the parameter documentation.

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 function: 'Make a prepared proposal live on the customer's website.' It uses a specific verb ('apply') and resource ('configuration proposal'), and distinguishes it from the sibling propose_configuration by explicitly naming that tool. The purpose is unambiguous and an agent can easily tell this apart from related tools like rollback_configuration or describe_configuration.

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

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

The description provides explicit when-to-use guidance: 'Only call this after showing the person the differences from propose_configuration and getting their agreement.' It also names the sibling tool propose_configuration as the prerequisite step, and warns about a condition that blocks usage ('Refused if the locator changed since the proposal was prepared'). This is strong, actionable guidance for an agent deciding when to invoke the tool.

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 this is a non-read-only, non-idempotent, non-destructive operation. The description adds valuable behavior beyond annotations: automatic geocoding of plain addresses, lat/lng override behavior, and quota impact ('Counts against the plan's location allowance'). It does not describe return values, but the safety profile is already carried 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?

Three short sentences, each earning its place: purpose, geocoding behavior, and quota consequence. It front-loads the core action and avoids repeating detailed schema 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 22-parameter create tool with no output schema and minimal annotations, the description covers the essential non-obvious context: what the operation does, geocoding behavior, and plan allowance impact. It does not address return values or duplicate handling, but the schema is rich enough that these are 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?

The description adds a cross-parameter decision rule: a plain address is geocoded automatically and lat/lng are only needed to override that result. With schema description coverage at 64%, this helps compensate for undocumented parameters, though many fields still rely on their schema descriptions for full 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 states a specific verb ('Add') and resource ('a location to the locator'), which clearly distinguishes it from sibling tools like update_location, delete_location, get_location, and list_locations. The title reinforces the action without ambiguity.

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

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

The description implies when to use the tool through 'Add a location' and gives conditional parameter guidance about geocoding, but it does not explicitly name alternatives or state when to prefer create_location over update_location. The allowance warning is useful context but not 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?

Annotations already indicate destructive=true and readOnly=false, but the description adds essential non-obvious behavior: this is a soft delete, the row is retained for analytics, and restoration is possible from the dashboard.

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 tightly written sentences: the first states the action, the second explains the retention and restoration behavior. No wasted words or repetition of schema/annotation details.

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 single-parameter delete operation with annotations covering safety and an idempotency hint, the description supplies the one crucial non-obvious detail (soft delete). Nothing needed to invoke the tool correctly is missing.

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

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

With 100% schema description coverage, the sole 'id' parameter is fully documented by the schema. The description adds no extra parameter-level meaning, so 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?

Description uses a specific verb and resource ('Remove a location from the locator') and goes beyond the title by clarifying the delete is soft. This distinguishes it from related siblings like update_location and get_location.

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

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

The context is clear: use this when a location needs to be removed while preserving analytics history. It doesn't explicitly name alternatives or exclusion conditions, but the soft-delete framing makes the intended use unambiguous.

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, and destructiveHint=false, so the safety profile is covered. The description adds value by explaining the tool returns the complete schema with current values, which helps the agent understand the response's scope and purpose. It doesn't contradict 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-loads the core purpose, and every sentence earns its place. The first sentence defines the output; the second gives actionable usage guidance.

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

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

For a zero-parameter read-only tool, the description is nearly complete. It explains what the tool returns and when to call it. The only minor gap is that it doesn't explicitly mention the output format or size, but the description's mention of 'complete configuration schema' sufficiently sets expectations.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify. The description compensates by explaining what the returned configuration contains, which is the relevant semantic information for this tool.

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

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

The description clearly states the tool's purpose: it returns the complete configuration schema with current values, covering behavior settings, brand tokens, result-card layouts, and visitor-facing wording. It distinguishes itself from sibling tools by emphasizing it is the full configuration snapshot, not a partial or mutation tool.

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

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

The description explicitly instructs to call this tool before proposing any change, so the agent uses real keys and allowed values. This provides a clear when-to-use directive and implicitly distinguishes it from mutation tools like apply_configuration or propose_configuration.

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, and destructiveHint=false, lowering the burden on the description. The description adds useful context beyond the schema: ranking is widget-consistent, and the tool behaves differently without a point. It does not describe output format, but that is a minor gap given the read-only 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 with no filler. The primary behavior is front-loaded, and the second sentence efficiently introduces the alternative mode. Every word contributes to understanding.

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 read-only tool with a fully documented schema and zero required parameters, the description provides enough to understand the two invocation patterns. The absence of an output schema is not fully compensated, but 'rank locations' implies the result shape, leaving only minor ambiguity about edge-case calls with no parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond individual parameter docs by revealing the relationship between lat/lng and q/tag: a point drives distance ranking, while q/tag can substitute for it to answer data questions.

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

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

The description uses a specific verb ('rank') with a clear resource ('locations') and criterion ('by distance from a point'). It also adds a second mode with 'tag or q without a point', which distinguishes this from a plain listing tool like list_locations.

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 clearly states when the primary ranking behavior applies (when a point is provided) and when the alternative data-question mode applies (tag/q without a point). It does not explicitly compare against sibling tools or state exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read behavior is known. The description adds that the return value is an HTML snippet plus public site id and where it should be pasted. No contradictions, but it does not disclose any caveats beyond that.

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 short sentences: the first states the output precisely and the second gives placement guidance. No filler or redundant details.

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

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

For a zero-parameter, read-only tool, the description covers the main purpose slash output and usage context. It does not detail the exact HTML shape or whether the snippet requires authentication, but with no parameters and readOnly annotations, enough context is present for an agent to use it.

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

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

The input schema is empty with 100% coverage and zero parameters, so no parameter documentation is needed. The description correctly avoids inventing parameters and instead focuses on the returned artifact.

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 resource (embed code for this locator) and the verb is implied by the title ('Get'). It also adds concrete detail: the output is an HTML snippet plus a public site id, which distinguishes it from sibling tools like get_location that return different 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?

It conveys the usage context: the embed code is meant to be pasted into a website where the map should appear. It does not explicitly enumerate alternatives or when-not-to-use, but for a zero-parameter retrieval tool this is adequate.

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, and destructiveHint=false. The description adds minimal behavioral context beyond that — it mentions the output includes hours and custom fields but does not disclose any side effects, auth needs, or rate limits. It neither enriches nor contradicts the annotations.

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

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

The description is a single, front-loaded sentence: 'Full details for one location, including hours and custom fields.' It conveys the core purpose immediately with zero filler or redundancy.

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

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

This is a simple get-by-id tool with one parameter, and annotations cover the safety profile. The description mentions key output fields (hours, custom fields) but does not fully enumerate all return details; however, 'full details' implies completeness. Adequate for the simplicity, though a touch more specificity about output structure would be ideal.

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 description for the 'id' parameter is clear ('Location id.'), and coverage is 100%. The tool description adds no extra semantic detail about the parameter, so the baseline score of 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 clearly states the tool retrieves full details for one location, including hours and custom fields. This distinguishes it from list_locations (which presumably returns summaries) and find_nearest_locations, and the resource and scope are 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?

No guidance is provided on when to use this tool versus alternatives like list_locations or find_nearest_locations. The description lacks any context about prerequisites or scenarios, leaving the agent to infer usage from the name alone.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description adds useful behavioral context beyond them: the result order ('newest first') and the inclusion of causal information. This is meaningful, though it does not detail the full return payload shape.

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 short sentences with no redundancy. The core object and ordering are front-loaded, followed by the practical use case, so every sentence earns its place.

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

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

For a simple read-only listing tool with one optional parameter, the description covers what is returned, the ordering, and the typical use case. There is no output schema, so slightly more detail about each version object could help, but the description is sufficient 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 100% because the only parameter, limit, is documented with its default and maximum. The description adds no parameter-specific meaning, which is acceptable given the schema already handles it.

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

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

The description states a specific verb ('list') and resource ('configuration history'), and immediately specifies ordering and content ('newest first, with what caused each version'). The rollback use case helps distinguish it from sibling configuration tools like describe_configuration and rollback_configuration.

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 explicitly tells the agent when to use the tool: to find a version number to roll back to. It does not name alternatives or state when not to use it, but the intended workflow context is clear enough for tool selection.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the result ordering ('newest first') and the locator-scoped nature of the list.

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, with the core purpose and ordering front-loaded, followed by a helpful usage hint. 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?

The description is sufficient for a simple read-only list operation: it states scope, ordering, and a search usage hint. It doesn't explain return shape, but there is no output schema and the operation is low-complexity, so this is an acceptable 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 75%, so most parameters already have descriptions. The description adds modest emphasis on using 'search' for finding by name or address, but doesn't meaningfully expand on limit, offset, or visibility semantics beyond what the schema provides.

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 ('List') and resource ('locations on this locator') and adds ordering ('newest first'). This clearly distinguishes it from sibling tools like get_location (single resource) and list_tags (different resource type).

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

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

The description gives clear context for using the search parameter to find a specific location before editing, which is actionable guidance. It doesn't explicitly name alternative tools or exclusion conditions, but the intended use case is reasonably 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations by stating the output includes how many locations carry each tag, which is not visible from the schema.

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

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

The description is a single, tightly written sentence that conveys the subject, scope, and output detail without wasted words. It is front-loaded with the core purpose and adds context only where it helps.

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

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

For a zero-parameter, read-only list tool with no output schema, the description is complete: it states what is listed, the per-tag counts, and the role of tags in the map filtering context. No critical information is missing for an agent to invoke it correctly.

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

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

The input schema has no parameters, so the description has no need to explain parameter meaning. The baseline of 4 is appropriate because no parameter documentation burden exists.

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 lists tags/categories on the locator and includes the count of locations carrying each one. It also distinguishes the resource from sibling tools by explaining tags are what visitors filter by on the map, so it cannot be confused with tag_locations or list_locations.

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: this tool is for retrieving the tags available for filtering and their usage counts. It doesn't explicitly name alternatives or state when-not-to-use, but the read-only, informational purpose is evident from the description and annotations.

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=false, destructiveHint=false, idempotentHint=false, so the agent knows this is a non-read, non-destructive, non-idempotent operation. The description adds valuable behavioral context beyond annotations: it returns the exact list of differences, it does NOT apply the change, and it is a proposal/preparation step. It doesn't describe side effects like whether a proposal record is persisted, but the 'Stored with the proposal as its record' note in the request parameter partially covers that. With annotations carrying the safety profile, a 4 is appropriate.

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, each earning its place: the first states the core behavior and return value, the second gives the required human-in-the-loop workflow, the third gives the prerequisite call. The most important constraint (WITHOUT applying it) is front-loaded. Zero 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?

For a proposal tool with 6 params, 100% schema coverage, and no output schema, the description covers the critical workflow context: what it returns (diff list), what to do with it (show to person), and what to call before/after (describe_configuration/apply_configuration). It doesn't describe the output format of the diff list, but the description explicitly says 'Returns the exact list of differences' which is sufficient for an agent to know what to expect. The nested objects are documented in the schema. A 4 is appropriate – complete for the agent's decision-making needs.

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%, so the schema already documents all 6 parameters. The description adds one meaningful cross-parameter constraint: 'Call describe_configuration first so the keys are real' – which tells the agent that settings and labels keys must come from describe_configuration. However, it doesn't explain the nested structure of layouts or branding beyond what the schema already provides. Baseline 3 is correct when the schema does the heavy lifting.

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 ('Prepare'), a clear resource ('a change to how the locator looks or behaves'), and an explicit non-goal ('WITHOUT applying it'). It also distinguishes itself from apply_configuration by naming the sibling and the exact relationship. This is a model of purpose clarity.

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

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

The description gives explicit when-to-use guidance: call describe_configuration first so keys are real, and show the returned diff list to the person and get agreement before calling apply_configuration. It names the alternative tool and the sequencing condition. Nothing is left to inference.

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

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

The description goes beyond the destructiveHint annotation by explaining that rollback creates a new version instead of erasing history, making the operation reversible. This is valuable behavioral context that helps an agent understand side effects despite the destructive hint. No contradiction with annotations is present.

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

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

The description is two sentences with no filler. It front-loads the core action and then adds the key behavioral nuance, making it easy to scan and understand.

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 one-parameter tool with annotations, the description is largely complete: it explains the operation, the main side effect, and the reversibility. It does not describe return values or explicitly guide alternative tool selection, but these are minor gaps given the 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 100% and the only parameter, targetVersion, is already documented as 'Version number to restore, from list_configuration_versions.' The description adds no additional parameter-level detail, which is acceptable given the complete 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 states a specific action and resource: 'Restore a previous configuration version.' It adds a useful distinction—rollback creates a new version rather than erasing history—so the tool's purpose is clear. However, it does not explicitly differentiate from sibling tools like apply_configuration.

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 intended use (restoring a previous configuration version) is implied by the description, but no explicit when-to-use or when-not-to-use guidance is provided. Alternatives such as apply_configuration or list_configuration_versions are not mentioned.

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 convey readOnly=false, idempotentHint=true, and destructiveHint=true. The description adds useful behavioral detail beyond that: URL values become clickable buttons, non-URLs render as plain text, and remove=true reverses the operation. It does not add much about overwrite or consequence depth, but the core behavior is clear.

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

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

Three sentences, front-loaded with the core purpose, with every sentence earning its place: scope, URL behavior, sibling exclusion, and remove mode. No filler or redundant restatement of the title.

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 7-parameter schema, the description covers the crucial distinctions and behavioral cases an agent needs to select and call the tool correctly. It could be more explicit about overwrite behavior for an existing key, but the schema plus annotations cover the remaining operational details reasonably well.

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%, so the baseline is 3; the schema already documents all parameters. The description reinforces the value semantics (URL vs plain text) and the remove flag, but it does not meaningfully add information beyond what the schema provides.

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

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

The description uses a specific verb and resource: 'Put the same extra field on many locations at once.' It also differentiates itself from tag_locations by explicitly stating it is NOT for tags or categories, so an agent can distinguish it from that sibling.

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 states when not to use the tool ('NOT for tags or categories') and names the alternative ('use tag_locations for those'). It also clarifies the remove mode for taking fields off, giving clear decision 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?

Annotations already signal mutating, non-destructive, idempotent behavior, so the description need not repeat that. It adds real behavioral context: creating missing tags, tags becoming visitor-facing filter chips, and the warning not to model tags as custom fields. These details shape expectations beyond the structured hints.

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

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

Five sentences, each carrying useful information: trigger phrases, create-if-missing behavior, domain semantics, custom-field exclusion, and prerequisite. There is slight redundancy with the title and schema, but no wasted words overall.

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 only three parameters, the description covers the operation's effect, tag semantics, how to source location IDs, and how this differs from custom fields. Combined with full schema coverage and annotations, an agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical value by telling the agent to call list_locations first for IDs and by clarifying the real-world meaning of tags, which supplements the schema descriptions without fully re-explaining each 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 concrete verb and resource: adds a tag to locations or removes it, and creates the tag if it does not exist. It also distinguishes the tool from set_custom_field with 'Never express a tag as a custom field,' so an agent can identify it unambiguously.

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 explicit trigger phrases ('tag these as X', 'add the X tag', 'categorise these as X') and declares itself 'THE tool for tagging.' It also provides a clear exclusion (not a custom field) and a prerequisite ('Use list_locations first to get the ids'), giving actionable when-to-use 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?

With annotations already declaring destructiveHint and idempotentHint, the description adds useful behavioral context: 'Only the fields you send are touched' and 'Changing the address re-geocodes it'. This reveals partial-update semantics and a side-effect beyond what the structured annotations provide.

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 that lead with the action, then cover the partial-update and re-geocoding side-effect. No filler or redundant detail.

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

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

For a complex mutation tool with 23 parameters and no output schema, the description covers core behavior but omits guidance on returning values, error conditions, or relationships among parameters (e.g., address/lat-lng). It does not mention set_custom_field as a more targeted option for custom fields.

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 65%, and the description adds little per-parameter meaning beyond what the schema already includes. It re-uses the address/re-geocoding behavior that appears in the schema and does not explain fields like postalCode, markerColor, or description, so it does not compensate for all 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 a specific verb ('Change') and names the resource ('an existing location'), making the tool's purpose immediately clear. It distinguishes the operation from create_location and delete_location without requiring 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?

The description implies usage: update an existing location and only provide fields to change. However, it does not explicitly state when not to use this tool or name alternatives such as set_custom_field for custom-field-specific updates or create_location for new records.

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