Handled Locator

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

Annotations already declare readOnly=false, idempotent=false, and destructive=false. The description adds a genuinely important behavioral trait beyond the annotations: changes are not live until publish_territories is called, revealing a draft/staging model. It still omits auth requirements and whether postcodes append to or replace the existing set.

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

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

Two tight sentences with no waste. The core operation and its two modes are front-loaded, and the staging caveat follows immediately.

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

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

For a mutation tool with annotations covering the safety profile and a fully documented schema, the description is nearly complete, covering purpose, modes, and the publish dependency. It could be improved by clarifying append-vs-replace semantics, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents id, op, and postcodes in detail, including the include/exclude default and the free-text splitting behavior. The description restates the include/exclude concept but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — adding postcodes to a territory — and immediately clarifies the two operating modes ('Grant (include) or carve out (exclude)'). An agent can distinguish this from siblings like create_territory or delete_territory without opening a schema.

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

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

The description provides a clear workflow context by naming publish_territories as the step required to make changes live, which tells the agent this is a staging operation. However, it doesn't state explicit alternatives or when-not-to-use conditions (e.g., whether another tool adds postcodes differently).

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risk profile is covered structurally. The description adds real behavioral context beyond that: a mandatory human-consent workflow and a staleness-based refusal condition, which the agent could not infer from annotations. It stops short of saying whether the change is reversible or how to undo it (rollback_configuration exists but is not referenced).

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

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

Three tight sentences: action first, precondition second, failure mode third. No filler and nothing buried.

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

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

For a destructive, non-idempotent, open-world mutation with no output schema, the description covers the action, the consent requirement, and the refusal condition. It could go further by noting recoverability or pointing at rollback_configuration for undoing a bad apply, but nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter's description already states it is 'the id returned by propose_configuration.' The description reinforces the proposal origin but adds no format, validation, or semantics beyond the schema, so baseline 3 applies.

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

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

'Make a prepared proposal live on the customer's website' is a specific verb+resource statement, and the pairing with propose_configuration makes clear what artifact it operates on versus its sibling. An agent can distinguish this from propose_configuration, describe_configuration, and rollback_configuration without opening a schema.

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

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

It gives an explicit precondition ('Only call this after showing the person the differences from propose_configuration and getting their agreement') and an explicit when-not ('Refused if the locator changed since the proposal was prepared'). That is a clear usage gate and failure condition tied directly to the sibling 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: automatic geocoding, batch semantics, that the reply identifies which entries landed, and that the call consumes the plan's location allowance.

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

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

Four tightly written sentences, front-loaded with the core action, then geocoding behavior, batch guidance, and the quota caveat. Every sentence carries distinct information and none is padding.

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

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

For a 26-parameter tool with nested objects and no output schema, the description covers the key call-shaping decisions (single vs batch, geocoding override, quota impact). It omits return-shape detail beyond 'the reply says which ones landed', but the schema carries the field-level burden, so the coverage 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 69% and the schema itself is unusually rich, documenting hours/hoursPatch semantics, locationType, customFields shape, etc. The description's parameter notes (address geocoding, lat/lng override, the `locations` array for batching) largely restate what the schema already states, adding little meaning on top.

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

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

The description states a specific verb and resource ('Add one location, or many in a single call') and immediately clarifies the scope, single vs batch, which lets an agent distinguish it from update_location and delete_location without opening the schema.

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

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

It gives clear operational context: use the top-level fields for one location, pass `locations` as an array to add up to a batch, and supply lat/lng only to override geocoding. It stops short of naming the alternative siblings (e.g. update_location for edits), so no explicit exclusions.

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

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

Annotations already declare it is a non-read-only, non-destructive, open-world, non-idempotent write. The description adds genuinely non-structured behavior: the rule goes live immediately and is evaluated after pre-existing rules, which affects conflict outcomes. It does not cover failure modes or required permissions.

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, both front-loaded: the structural contract (trigger + action) comes first, then the enablement/ordering behavior, then the id cross-reference. No filler and nothing redundant.

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

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

For a 7-parameter nested write tool with no output schema, the description covers shape, activation state, ordering, and id sourcing, and the annotations carry the safety profile. What is missing is narrower: permission requirements and whether a rule id is returned or must be re-fetched via list_spotlight_rules.

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 enum/nested-object descriptions are unusually thorough, so the baseline is 3. The description adds only the 'one trigger, one action' constraint and the list_locations pointer for location ids — helpful, but marginal against a schema that already documents every field and value.

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

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

States a specific verb and resource ('Add a rule') and immediately defines the rule's shape: one trigger, one action. The create_/update_/list_/delete_ naming makes the sibling split inferable, but the description itself never names the adjacent siblings (update_spotlight_rule, list_spotlight_rules), so it stops just short of a 5.

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

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

Gives real operational context — the rule is enabled on creation and ordered after existing rules — and points to list_locations for sourcing location ids. It never says when to use this versus update_spotlight_rule or set_spotlight_rule_enabled, so usage is implied rather than specified.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so safety is partly covered, but the description adds genuinely useful state behavior: the new territory is inert (covers nothing) and has no visitor effect until two later operations run. It doesn't address authentication, duplicate-name handling, or whether the created record can be rolled back.

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

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

Three short sentences, front-loaded with the core action and then the lifecycle caveats. Every sentence carries distinct information and none restates the tool name or schema.

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

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

With no output schema, the description could have noted that the created territory's identifier is needed for the follow-up add_territory_postcodes call, which is a minor gap. Otherwise it fully explains the entity's initial state and downstream dependencies for a non-destructive mutation.

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 all four parameters are already documented in the schema, including the rank tie-break rule and exclusive routing. The description only mildly reinforces semantics by glossing locationId as the owning dealer; it adds no format or constraint detail 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?

States a specific verb and resource ('Create an empty territory') and immediately qualifies the result with ownership ('owned by one location (dealer)'). It differentiates itself from neighbors by naming add_territory_postcodes and publish_territories as the steps that give the territory meaning.

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

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

Clearly frames this as the first step in a workflow: the territory covers nothing until add_territory_postcodes, and nothing reaches visitors until publish_territories. It does not state any when-not-to-use condition or mention alternatives such as updating an existing territory, so it stops short of full routing 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 declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is partly supplied. The description adds materially beyond that by disclosing the soft-delete semantics, that the row is retained for analytics history, and that the change is reversible from the dashboard — behavioral context an agent cannot derive from the schema or annotations alone.

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

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

Three short sentences, front-loaded with purpose, then the non-obvious soft-delete behavior, then the parameter choice. No sentence is redundant and nothing important is buried.

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

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

With no output schema, the description adequately covers what the operation does and what happens to the data afterwards (retention, restorability). It is slightly short on batch return semantics — e.g., what happens on partial failure when deleting up to 200 ids, or whether a de-eliminated id errors — but for a two-parameter tool this is close to 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 100% and both properties are already documented in the schema, including the mutual exclusivity note and the 200 maxItems constraint. The description restates the id/ids choice and the batch limit without adding format or failure-handling detail beyond the schema, so the baseline 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 opens with a specific verb+resource ('Remove a location from the locator'), and the resource name cleanly separates it from the sibling delete_spotlight_rule and delete_territory tools. It also immediately qualifies the operation as a soft delete, so the agent knows this is not a hard purge.

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 how to choose between the two parameters ('Pass `ids` instead of `id` to delete up to 200 in one call'), which is useful invocation guidance. It gives no guidance about when to delete versus deactivate/update a location, or when this tool should be avoided in favor of update_location or a territory operation, so tool-level routing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered. The description adds value beyond them by declaring the effect is immediate and irreversible, which an agent needs to weigh before calling. It does not mention auth/permission requirements or error behavior, keeping it from a 5.

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

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

Two tight sentences with no filler; the destructive consequence is front-loaded and the id source follows. Every clause earns its place.

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

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

For a one-parameter destructive tool with full annotations and no output schema, the definition covers purpose, irreversibility, and id sourcing. It omits only permission requirements and any failure modes, which are minor gaps here.

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% on the single id parameter, setting a baseline of 3. The description adds provenance the schema lacks ('Get the id from list_spotlight_rules'), telling the agent how to obtain a valid value rather than only what the field means.

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?

Specific verb (delete) plus resource (a rule), and it goes further by stating the consequence ('stops applying at once and cannot be restored'), which separates it from reversible siblings like set_spotlight_rule_enabled and update_spotlight_rule. An agent can tell instantly this is a permanent removal, not a disable.

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 routes the agent to list_spotlight_rules as the source of the id, giving a concrete precondition for invocation. It implies but does not explicitly state the alternative path for reversible action (disable via set_spotlight_rule_enabled), so it falls slightly short of full when-to-use/when-not 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 declare destructiveHint=true, but the description adds behavior annotations cannot express: the deletion cascades to the territory's rules, and the change is not visitor-visible until publish_territories runs. That is exactly the 'what gets destroyed / when it takes effect' context that matters for a destructive call.

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, zero waste: the action is front-loaded and the publish-lag caveat follows immediately. Every clause earns its place.

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

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

For a one-parameter, no-output-schema destructive call, the description plus annotations cover everything needed to invoke it correctly: what is deleted, that rules go with it, and that effects are deferred until publish.

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 single required 'id' parameter is already documented, and the description adds nothing about its format or source. Baseline 3 per the high-coverage rule.

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

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

States a specific verb and resource ('Delete a territory') and adds the cascade scope ('and its rules'), which distinguishes it from delete_location and delete_spotlight_rule without opening a schema. The destructive scope 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?

Names the required follow-up action (publish_territories) and the consequence of skipping it, which is genuine workflow guidance an agent needs. It stops short of explicitly contrasting this tool with delete_location or delete_spotlight_rule, so no exclusion guidance is given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the tokens are computed values that are stored nowhere, and the full output is roughly 30KB — useful expectations for an agent deciding whether to page through output. 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?

Three sentences with zero waste: the first states the output, the second gives use case and routing, the third explains the parameter. The most decision-relevant information (what it returns and when to use it) is front-loaded, and the sibling routing is compact.

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 one optional parameter, no output schema, and annotations covering the safety profile, the description is complete: it states the return content, the size implication, the section scoping, and the write-tool alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the enum values each carry detailed explanations of what they return, so the schema does the heavy lifting. The description adds modest value beyond that: clarifying the default (all) and framing section as a way to avoid the full 30KB payload, which is useful but does not change the baseline for fully documented 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 states a specific verb (read/describe) and resource (the locator configuration), and enumerates exactly what is returned: behaviour settings, brand tokens, result-card layouts, and visitor-facing wording, each with the schema beside it. It also distinguishes itself from the write sibling propose_configuration, so an agent can differentiate the tools without opening schemas.

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 this tool ('Use it to read what is set now') and when not to ('To write a change you do not need it'), naming propose_configuration as the alternative and explaining why (its input schema lists every key and allowed value). It also gives guidance for the optional section parameter as a way to scope the read.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds value by disclosing that results come only from published territories and reflect visitor routing, i.e. unpublished edits will not affect the answer — a non-obvious behavioral constraint an agent should know.

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

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

A single tight sentence with no filler, and the key scoping constraint (PUBLISHED) is front-loaded. It loses a point only because the sentence is a fragment and the object it explains is stated indirectly.

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

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

For a 3-parameter, read-only lookup with full schema coverage and no output schema, the description supplies the essential framing: what is being explained, why the answer has rationale, and which territory state it derives from. Only the shape of the returned explanation is left unstated, which is acceptable here.

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 lat, lng and the conditional postcode rule are already documented in the schema (including the warning that postcode rules cannot match without postcode). The description adds no parameter-level meaning beyond that, so the baseline 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 states a specific question it answers ('Which dealer owns a point, and why') and pins the data source to PUBLISHED territories. It reads clearly as a query/explanation tool distinct from list_territories or publish_territories, though it never names a sibling to route against.

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?

'Answered from the PUBLISHED territories, exactly as a visitor there would be routed' implies when to reach for it (visitor-facing truth, not draft config), which is meaningful context for a repo full of propose/apply/publish tools. But there is no explicit when-not or named alternative, so the selection guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true, 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 establish read-only, idempotent, and non-destructive behavior. The description adds useful context by disclosing the exact return payload: an HTML snippet carrying a public site ID. This is sufficient for a simple getter.

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 main deliverable and ending with actionable placement guidance. There is no filler or redundant restatement.

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 tool with no required parameters and no output schema, the description explains enough about the return value and how to use it. It only lacks minor cross-tool routing context, which is already captured under usage guidelines.

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 describes both parameters fully with 100% coverage. The description does not add parameter-level meaning, but the baseline 3 applies because the schema already carries the burden.

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 what it returns (an HTML snippet plus the public site ID), going beyond the title. However, it does not explicitly contrast with siblings or use a direct retrieval verb.

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 last sentence implies a use case: paste the snippet where the map should appear on a website. But there is no explicit guidance about when to choose this tool over siblings or when to use the optional near/tags parameters.

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, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the list is returned in application order (after territories) and includes ids. It says nothing about pagination or result size, which is the only remaining gap.

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

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

Two sentences, no filler. The clarifying domain sentence comes first and the action plus guidance follows, which is reasonable front-loading for a concept-heavy resource, though the opening could be tightened slightly.

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

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

With no output schema, the description carries the burden of saying what comes back, and it does mention ordering and ids. Nothing prevents a correct zero-arg call; only pagination/volume details are 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly describes a call that requires no arguments and does not invent any filtering semantics.

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 gives a specific verb and resource ("Lists every rule") and defines what a spotlight rule is with concrete examples (banner, featured locations, hidden locations). It also distinguishes ordering from territories ("after territories"), but never names a sibling tool, so the differentiation is implied rather than explicit.

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

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

"Call this before changing a rule" clearly establishes the context of use and points at update_spotlight_rule / set_spotlight_rule_enabled / delete_spotlight_rule without naming them. There is no explicit when-not-to-use guidance, but the trigger condition is 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, 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the returned fields, the existence of a 'published version', and the state relationship that nothing reaches visitors until publish_territories — meaningful behavioral disclosure about domain state.

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, reasonably front-loaded: it establishes the concept, then the concrete output, then the publish caveat. The opening 'who OWNS an address, as distinct from who can reach it' framing is slightly elaborate for a list tool, but overall it is tight and every sentence carries information.

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

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

For a zero-parameter list tool with annotations covering safety and no output schema, the description explains what is returned (owner, rank, rules, id, mode, published version) and the relevant publish state, so an agent knows what it gets. It omits any note on ordering or size limits, which is a minor 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?

The tool takes zero parameters, so per the rubric the baseline is 4. Schema coverage is 100% and there is nothing further a description could add about inputs.

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

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

States a specific verb and resource ('Lists every territory with its owner, rank, rules and id, the territory mode, and the published version'), which is concrete and unambiguous. It names the related sibling publish_territories, giving some differentiation, but the opening contrast against a 'service radius' is conceptual framing rather than a clear distinction from a listed sibling 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 frames what a territory is and notes the publish workflow ('Nothing reaches a visitor until publish_territories'), which implies when this listing is useful. However, it never explicitly states when to use this tool versus siblings like explain_territory_owner or describe_configuration, so usage is only implied.

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

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

Annotations already declare destructiveHint=false, and the description reinforces that with 'WITHOUT applying it'. It adds genuinely new behavior: the tool returns an exact diff, and a rejected patch reports every wrong key and value at once. It doesn't mention whether proposals expire or are stored beyond the request record, but that is a minor gap.

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

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

Front-loads the non-applying, diff-returning nature, then the confirmation workflow, then the patch-writing rule. Every sentence carries a distinct instruction with no padding.

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

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

For a very large nested schema with no output schema, the description covers what matters most: the return value (exact list of differences), validation feedback, and the human-approval gate before apply_configuration. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema documents all six parameters and their nested keys. The description adds only the operational rule to send partial patches rather than the full object, which is useful but not syntax or format detail beyond the schema; 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?

States a specific verb and resource ('Prepare a change to how the locator looks or behaves') and immediately narrows scope with 'WITHOUT applying it'. An agent can distinguish this from apply_configuration without opening either schema.

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

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

Explicit workflow: show the returned diff to the person and get agreement before calling apply_configuration, naming the sibling that does the apply. It also specifies the patch-writing rule ('only send the keys you want to change'), leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the bar is lower — yet the description still adds real behavior: it creates a new version and only swaps visitor routing 'once every file is written', disclosing an all-or-nothing publish characteristic not expressed by any annotation.

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

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

Two short sentences, no filler, with the core action ('make live') front-loaded and the operational caveat second. Every clause carries information.

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

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

For a zero-parameter, no-output-schema tool with a rich annotation set, the description covers what is produced (a new version) and what changes (visitor routing). It stops short of naming the recovery path (rollback_configuration) or any permission requirements, which would make an irreversible-feeling publish fully self-contained.

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 takes zero parameters, so per the rules the baseline is 4; there is nothing for the description to clarify, and it correctly does not invent parameter semantics.

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?

Specific verb-plus-resource: it states it publishes (makes live) the current territories, which is clearly distinct from siblings like list_territories, create_territory, or rollback_configuration. An agent can identify the operation without opening the schema.

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

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

The phrase 'make the current territories live' implies when this is used, and the sibling set contains adjacent tools (apply_configuration, rollback_configuration, propose_configuration), but the description never names an alternative or states a precondition for choosing this one over them.

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 destructiveHint=true and idempotentHint=false already declared, the description adds genuinely non-obvious behavior: the rollback is non-erasing because it writes a new version, and is therefore itself reversible. That materially informs the agent's risk assessment beyond what the annotations state.

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

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

Two tight sentences with zero filler; the core action is stated first and the consequence follows as justification. Every clause earns its place.

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

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

For a single-parameter mutation with annotations covering the safety profile, the description explains the key outcome (a new version is created). It does not mention failure modes or what the call returns, which is a minor gap given there is no output schema.

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

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

Schema description coverage is 100% and the single parameter already documents its format and points at list_configuration_versions as the source. The description adds no further parameter constraints, so the baseline 3 applies.

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

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

The description states a specific verb and resource: restoring a previous configuration version. It is clear what the tool does and implicitly contrasts with version-mutating siblings like apply_configuration and propose_configuration, but it never names an alternative to disambiguate the choice.

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

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

Usage is only implied by 'restore a previous configuration version.' There is no explicit statement of when to prefer rollback over apply_configuration, propose_configuration, or publish_territories, and no prerequisites or exclusions are given.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real behavioral detail: URL values render as clickable buttons versus plain text, and the remove flag performs the destructive operation. It does not mention permission requirements or the batch limit, so it falls short of full behavioral disclosure.

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

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

Three sentences, front-loaded with the core action before the exclusion and the removal flag. The aside 'which are a different thing entirely' is slightly padded, but nothing important is buried.

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

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

With 7 parameters, no output schema, and rich annotations, the description covers rendering behavior, removal, and sibling routing, which is enough to call the tool correctly. It omits the 200-location cap (schema handles it) and any failure/partial-success behavior.

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

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

Schema description coverage is 100%, so every parameter is already documented, including the URL-to-button rule and the remove semantics. The description largely restates those same facts (URL becomes a button, remove takes the field off) rather than adding syntax, defaults, or edge cases beyond the schema. 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?

States a specific verb and resource with scope ('Put the same extra field on many locations at once') and grounds it with concrete examples (booking button, social link, labelled fact). It explicitly separates itself from tag_locations, so an agent can distinguish it from siblings without reading the schema.

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

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

Gives an explicit exclusion ('NOT for tags or categories') paired with the named alternative (tag_locations), plus the conditional action for deletion ('Set remove to true to take the field off instead'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare destructiveHint=false and idempotentHint=true, so the safety and repeatability profile is covered structurally. The description reinforces the non-destructive nature with 'without deleting it', but adds no permission, rate-limit, or state-transition detail 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, zero padding, and the core action is front-loaded ahead of the id-sourcing tip.

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 trivial two-parameter toggle with full schema coverage and annotations carrying the safety profile, the description covers action, non-destructiveness, and id provenance adequately. Only a note on what happens if the id is invalid would improve 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?

Schema description coverage is 100%, and the schema itself explains both `id` and the true/false meaning of `enabled`. The description adds no syntax or format detail beyond the schema, so the baseline 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?

States a specific verb+resource ('Turn a rule on or off') and explicitly distinguishes itself from the delete path with 'without deleting it', which separates it from delete_spotlight_rule and update_spotlight_rule in the sibling list.

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

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

Gives a clear prerequisite/entry point by naming list_spotlight_rules as the way to obtain the id. It does not explicitly say when to prefer this over update_spotlight_rule, but the toggle-vs-edit distinction is implicit in the phrasing.

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

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

Annotations already declare idempotentHint=true, destructiveHint=true and openWorldHint=true, so the safety profile is largely covered. The description usefully adds partial-update semantics ('Only the fields you pass are changed'), which reinforces idempotency, but it never explains why a pure styling operation is flagged destructive or what state (prior colour/group) is overwritten.

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

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

Six short sentences, front-loaded with the core action and scoping facts, with the sibling pointer last. Every sentence carries distinct information; 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?

No output schema exists, but the tool is a simple field-mutating setter and the description plus schema cover inputs, preconditions and the alternative path. The only gap is the unexplained destructive annotation, which is minor given annotations are otherwise present.

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 tag, color, group and the icon enum. The description largely restates these (exact tag name, same-group rendering, hex colour) rather than adding new semantics such as default values or format rules.

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

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

States a specific verb and resource ('Change how an existing tag looks') and enumerates the exact stylable facets (filter group, chip colour, icon). It is unmistakably distinct from siblings like tag_locations and list_tags.

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

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

Explicitly names the precondition ('The tag must already exist') and routes the create-and-style case to the named alternative 'tag_locations'. Both when-to-use and when-not-to-use are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond that: the change takes effect on the live locator immediately, which tells the agent this is a production-affecting write rather than a staged draft edit.

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, zero filler, with the core purpose front-loaded and the live-application caveat placed second. Every clause carries information an agent needs.

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-enum, mutation-flagged tool with annotations covering safety and idempotency and no output schema, the description is nearly complete: it explains what is being set and that it applies immediately. The one real gap is whether this interacts with the draft/publish workflow implied by siblings like propose_configuration, publish_territories and rollback_configuration.

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%, and the schema itself spells out each enum value (off, preferred, exclusive, fallback) in more detail than the description does. The description merely re-lists the four values, adding no syntax or semantics beyond the schema, so the baseline 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?

States a specific verb and resource ("Choose how territories affect a visitor's results") and names all four mode values, so the agent immediately knows the operation is a territory-scoping configuration switch. It does not explicitly contrast itself with adjacent setters like set_spotlight_rule_enabled or set_tag_style, but the territory framing is distinctive enough to separate it.

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

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

Usage is only implied: the four modes and their effect on visitor results suggest when each choice is appropriate, but there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g. versus explain_territory_owner or publish_territories). An agent can infer intent but is not told the conditions under which this tool should be preferred.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavioral context, namely that adding creates the tag when missing and that group/color/icon are applied atomically in the same call. It does not discuss permission requirements or failure behavior.

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

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

Front-loaded with the core add/remove semantics followed by side effects, styling, disambiguation and prerequisite in a logical order. Slightly repetitive ('Applied in this same call' echoes the schema), but every sentence carries information.

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

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

For a mutation tool with no output schema, it covers the creation side effect, the destructive removal path, atomic styling, and the id-sourcing prerequisite. Missing only auth/permission notes and the 200-id cap, which lives in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: that icon/color/group are applied in this same call rather than requiring a follow-up, i.e. tag creation, application and styling are one atomic operation.

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

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

States a specific verb (add/remove a tag) and resource (locations), and explicitly separates itself from near-siblings by noting 'tags are not custom fields' and that styling is bundled here rather than in set_tag_style. An agent can pick it out of the list without opening a schema.

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

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

Provides concrete user phrasings ('tag these as X', 'mark these as X') and a prerequisite step ('Get location ids from list_locations first'), plus the 'not custom fields' disambiguation. It stops short of naming set_tag_style or list_tags as explicit alternatives for styling/enumeration.

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

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

Annotations already supply the safety profile (destructiveHint=true, idempotentHint=true, readOnlyHint=false). The description adds real value on top: partial-update semantics ('only the fields you send are touched'), the re-geocoding side effect of an address change, and the constraint that address/coordinates/name are not batchable. It does not flag the destructive capacity of bulk updates explicitly, which keeps it from a 5.

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

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

Four compact sentences, front-loaded with the core operation, then side effects, then batch mechanics. No filler and no restatement of the tool name or 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?

For a 27-parameter mutation tool with no output schema, the description covers the operation model, batch path, and key side effects, while annotations carry the safety profile and the schema carries per-field detail. Coverage of the many optional fields is left entirely to the schema, which is acceptable but leaves the description slightly thin overall.

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

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

Schema coverage is 70% and the schema descriptions are already detailed, so the baseline would be 3. The description goes beyond it by defining the id/ids mutual exclusivity and the per-field batching restriction (address, coordinates, name stay one-at-a-time), which is not stated in the schema itself.

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

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

States a specific verb and resource ('Change one or more fields on an existing location') and immediately covers both single and bulk modes. An agent can distinguish this from create_location/delete_location without opening the schema, and the batch variant is called out in the title and body.

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 tells the agent when to use `ids` vs `id` and gives concrete batch scenarios (hiding a batch, setting priority across a region). It stops short of naming alternatives like create_location or delete_location, but 'existing location' frames the intended context clearly.

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 real context beyond the annotations: this is a full-replacement (PUT) operation where 'the previous values are overwritten', which sharpens the destructiveHint=true annotation into concrete behavior. It doesn't cover auth requirements or field-level validation, keeping it from a 5.

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

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

Two tight sentences, front-loaded with the replacement semantics and the overwrite warning, with the id-sourcing hint last. 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?

For an 8-param, nested-object, no-output-schema mutation tool, the description covers the key gotcha (full replacement) and id sourcing. Minor gaps remain around auth/permission needs and rejection of unknown fields, but the essentials are present.

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 meaningful parameter semantics by framing all fields as a full payload and enumerating the categories (name, trigger, action, dates) that must be sent together, reinforcing how the required fields must be used.

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

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

States a specific verb (Replace/update) and resource (a rule) plus the fields touched: name, trigger, action, dates. It is clearly distinguishable from create_spotlight_rule and delete_spotlight_rule, though it doesn't explicitly name those siblings.

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

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

Gives the crucial usage rule ('Send the whole rule, not only the changed part') and routes the agent to list_spotlight_rules to obtain the id. It stops short of explicitly contrasting with create/delete, but the context is clear.

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