Desk

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so safety is largely covered. The description adds a useful negative scope ('does not approve...'), but says nothing about permissions, side effects, or what creation produces beyond what annotations imply.

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 compact sentences, front-loaded with the action and followed by the exclusion. No wasted words, though the 'policy home' phrasing is slightly indirect.

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?

An output schema exists so return values need not be described, and annotations cover the safety profile. However, the undocumented parameters leave the definition partially incomplete for a mutation tool.

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

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

Schema description coverage is 0% for two parameters (name, description), so the description carries the full burden, yet it mentions neither. An agent gets no guidance on what 'name' means versus 'description' or format constraints.

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

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

States a specific verb+resource ('Create a support desk') and clearly separates it from the read sibling list_support_desks via the create semantics. The 'when the user asks for a new policy home' clause frames the intent, though it does not name alternative siblings explicitly.

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

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

Gives a triggering condition ('when the user asks for a new policy home') and a boundary ('does not approve answers, refunds, features, or timelines'), which helps the agent avoid misrouting to approval-type tasks. It stops short of pointing to the tool that does handle those approvals (e.g., save_approved_answer).

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 this as a readOnly, idempotent, non-destructive operation, so the safety profile is covered. The description adds genuinely useful outcome semantics beyond that: what REFUSED means operationally (do not say it, do not invent a substitute) and the constraint on APPROVED wording, plus the conditional effect of passing channel.

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 short sentences, front-loaded with the core decision, then outcome semantics, then the optional parameter effect. No filler. Slight opacity in the bare term 'sayOnly' (an output field not defined here) is the only friction.

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?

An output schema exists, so return values need not be restated, and the description still usefully clarifies APPROVED/REFUSED semantics. The remaining gap is that deskId's role and how the approved set is scoped are never addressed, which matters for a decision tool with a required deskId.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the 'kind' space implicitly (refund/feature/timeline) and gives the behavioral effect of 'channel' (enforcing the escalation limit), but deskId and the proposal string format/length are left completely unexplained.

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: deciding whether a proposed refund/feature/timeline is 'in the approved set', which maps directly onto the REFUND/FEATURE/TIMELINE enum. It is clearly distinct from list_approved_commitments, but it never names or contrasts with its closest sibling evaluate_escalation, leaving that differentiation to inference.

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 hints at usage via 'Pass channel to also enforce the escalation limit', which tells the agent one behavioral condition for invoking it. However, it never says when to reach for this tool versus evaluate_escalation or list_approved_commitments, so the routing guidance 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 cover read-only/idempotent/non-destructive semantics, so the bar is lower, and the description adds genuine behavioral meaning: how to interpret a REFUSED outcome ('do not escalate and do not invent a tier') and the downstream dependency on evaluate_commitment. It doesn't describe the response shape, but the output schema carries 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 tightly packed sentences with the decision framing front-loaded and no filler. Every clause (scope, REFUSED handling, evaluate_commitment dependency) carries actionable weight.

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 policy-decision tool with a rich annotation set and an output schema, the description covers the hardest parts: outcome interpretation and the chaining rule to evaluate_commitment. The remaining gap is the absence of any parameter-level guidance, but return values and safety semantics are otherwise well covered.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate and largely does not. It never explains deskId, channel, or targetTier, and only indirectly echoes the action enum values ('escalate...refund, feature, or timeline'), which gives minimal added meaning over the schema's enum.

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 decision verb and resource: deciding whether a channel may escalate or promise a refund/feature/timeline. It also distinguishes the sibling relationship by noting that promising requires evaluate_commitment for exact wording. The scope phrase 'this channel' is slightly context-dependent, but overall the purpose 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?

It gives an explicit conditional route: 'Permission to promise still requires evaluate_commitment for the exact wording,' which tells the agent when to chain to a sibling. However, it does not state when to call this versus the many other policy-lookup siblings (list_escalation_limits, list_refund_rules), nor any explicit when-not-to-use condition.

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 description earns credit for adding non-obvious interpretation guidance: results are evidence, not permission, and an absent answer must not be fabricated. It still omits behavioral detail such as how `limit` truncates the returned answers or what happens when a desk has no rules.

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 short sentences, front-loaded with the retrieval scope and followed by behavioral guardrails; nothing is padded. The two-sentence caution is slightly repetitious in tone but each sentence carries distinct 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?

An output schema exists, so return values need not be explained, and the description covers the tool's scope and the key downstream dependency. The remaining gap is parameter-level: with 0% schema coverage, an agent gets no explanation of `deskId` or the `limit` cap on how many answers come back.

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

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

Schema description coverage is 0% across three parameters, and the description only implicitly covers `question` ('for a customer question'). Neither `deskId` nor `limit` (default 8, max 20) is mentioned, so the description does not compensate for the schema's total lack of 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?

States a concrete verb ('Retrieve') and an explicit composite resource: approved answers for a customer question plus the desk's refund rules, commitments, and escalation limits. That bundled scope inherently separates it from the granular siblings (search_approved_answers, list_refund_rules, list_escalation_limits), so an agent can pick it 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?

Gives an explicit routing rule to a named sibling: 'Call evaluate_commitment before promising a refund, feature, or timeline,' and frames the output as evidence rather than authorization. It stops short of saying when to prefer the granular list_* tools over this aggregate call, so it is clear context without full when-not coverage.

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

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

Annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the burden is light. The description adds a useful semantic constraint ('listing does not approve a different promise') but says nothing about filtering behavior or what the returned set contains.

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 read purpose and followed by the workflow caveat. No padding, though the final instruction is slightly terse.

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?

An output schema exists, so return values need not be explained. However, with three parameters at 0% coverage and a kind enum, the description leaves the filtering semantics for deskId and includeRetired unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It only gestures at the kind values by naming 'feature and timeline statements'; deskId and includeRetired are entirely undocumented in both description and 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 (read/list) and resource (approved feature and timeline statements), so the agent knows what it retrieves. It doesn't explicitly distinguish itself from the similar sibling search_approved_answers, leaving some overlap unresolved.

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

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

Gives clear workflow context: listing does not itself approve a promise, and evaluate_commitment should be called with the exact wording before making a claim. That steers the agent toward the right follow-up tool, though it stops short of stating when to prefer this over search_approved_answers.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine domain context beyond that: the meaning of an APPROVED limit and the operational consequence of its absence, which helps the agent interpret results. It does not, however, describe pagination or filtering 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?

Two tight sentences with the action front-loaded and no filler. The second sentence is arguably domain guidance rather than tool description, but it is short and earns its place by clarifying the data's significance.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still, the description omits any parameter guidance despite 0% schema coverage and gives no routing versus siblings, leaving meaningful gaps for a tool with a required deskId.

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

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

Schema description coverage is 0% for two parameters, so the description must compensate and it does not: neither 'deskId' nor 'includeRetired' is mentioned or explained. The agent gets no guidance on the required desk scoping or on what including retired limits 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?

States a specific verb and resource ('Read escalation limits'), which is clear. However, it does not distinguish itself from sibling list tools such as list_approved_commitments or list_refund_rules, so an agent gets no help telling these apart from the description alone.

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 second sentence implies why the data matters (a channel without an APPROVED limit cannot promise anything), which hints at the relevance of reading these limits. But it never says when to call this tool versus the sibling list tools or what prerequisites (e.g., a valid deskId) are needed.

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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds substantive domain behavior: only APPROVED-status rules carry authority and that authority is exercised via evaluate_commitment, not by reading this list. It says nothing about what includeRetired surfaces, but the safety-relevant behavior is disclosed.

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, zero filler, with the core action and the domain constraint front-loaded. Every sentence carries distinct information: the operation, the authorization path, and the misuse warning.

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?

An output schema exists, so return values need not be described, and the authorization model is well covered. The remaining gap is the includeRetired parameter, whose meaning and effect on results is undocumented anywhere, leaving an agent unable to reason confidently about non-default invocations.

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

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

Schema description coverage is 0% for two parameters, so the description must compensate and it does not. Neither deskId nor includeRetired is explained, and the key semantics of includeRetired (what a 'retired' rule is, and why you would include one) is absent from both the schema and the description.

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

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

Uses a specific verb and resource with scope: 'Read refund rules on a desk.' This clearly separates it from the write sibling save_refund_rule and from the commitment-oriented listers. It stops short of explicitly contrasting with list_approved_commitments, so it lands at 4 rather than 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 usage constraints: only APPROVED rules authorize wording, authorization flows exclusively through evaluate_commitment, and the list itself is not permission to invent a refund. That is strong when-to/when-not guidance, though it never states when to prefer this lister over list_approved_commitments or get_desk_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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'use the returned id / do not guess' guardrail, useful context, but says nothing about pagination behavior tied to offset or result ordering.

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 purpose and followed by actionable instructions. Tight and mostly waste-free, though the id/do-not-guess guidance could be consolidated.

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 output schema exists so return values needn't be explained, and complexity is low (one optional param). However, for a tool whose whole point is fetching ids, the description omits any handling of the offset/pagination parameter, leaving a small but real gap.

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

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

Schema description coverage is 0% and the single 'offset' parameter is never mentioned in the description. Even though the schema supplies type, default and min/max, the description offers no compensation for the coverage gap or explanation of what offset does for this list.

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 ('List ... support desks') and scopes it to 'this team's', which distinguishes it from the workspace-wide sibling create_support_desk. It does not explicitly name a sibling like get_desk_context, so differentiation is implicit rather than stated.

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

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

Gives concrete workflow guidance: use the returned id, and do not guess a desk. This steers the agent to call this tool first before operations that need a desk identifier. It stops short of naming alternative tools or the full when-not condition.

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 and destructiveHint=false, so the description's 'identical retries keep the same revision' mainly reinforces that. The genuinely additive detail is the optimistic-concurrency contract: a changed answer requires expectedRevision from a previous read, which is not derivable from the annotations.

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

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

Three short sentences, each carrying distinct information: what it does, the retry contract, and the revision precondition. Front-loaded with the action and zero filler.

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

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

The presence of an output schema means return values need no explanation, and annotations cover the safety profile. However, for a 6-parameter mutation with no schema descriptions, the description leaves key semantics (notably what RETIRED does and whether it removes or archives the answer) unaddressed.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the full burden — but it only explains expectedRevision. It never clarifies status (APPROVED vs RETIRED), what deskId scopes, or the length constraints on topic/question/answer, leaving most parameters undocumented anywhere.

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

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

The description names a specific verb pair (store/revise) and resource (an approved answer), and the 'explicitly approved' qualifier distinguishes it from the read-oriented sibling search_approved_answers. It does not explicitly distinguish itself from save_approved_commitment, but the resource noun is clear enough to route correctly.

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 states the precondition for use (the user has explicitly approved the answer) and gives a concrete conditional rule: a changed answer requires expectedRevision from a prior read. What is missing is an explicit pointer to alternatives (e.g., search_approved_answers for reads), 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=false, destructiveHint=true and idempotentHint=true, and the description adds useful context (only the approved wording passes evaluate_commitment, plus the approval precondition). However, it never explains the destructive/retirement side implied by destructiveHint and the RETIRED status value, nor how expectedRevision conflicts are handled. With annotations carrying the safety profile, this is adequate but leaves the mutation semantics thin.

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 action and followed by the relational constraint and the exclusion. No filler; every sentence 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?

An output schema exists, so return values need not be described. But for a mutation tool flagged destructiveHint=true with a RETIRED status and an optimistic-concurrency parameter, the description omits overwrite/retirement behavior and revision handling, leaving the agent partially informed.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, yet it only loosely gestures at kind ('feature or timeline') and statement ('the statement'). deskId, name, status and expectedRevision receive no explanation at all, including the concurrency meaning of expectedRevision.

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 (store) and resource (a feature or timeline statement), which cleanly separates it from sibling savers like save_approved_answer, save_escalation_limit and save_refund_rule. It does not explicitly name any sibling, so it stops 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?

Provides a real precondition ('the user has explicitly approved') and an exclusion ('Do not save a date or a feature the user did not approve'). It does not name an alternative tool or explain what to do instead, but the when-to-use 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 this a destructive, idempotent write, and the description adds real behavioral context beyond them: maxTier must be a member of tierLadder, the three promise flags default to closed, and the important semantic caveat that saving a limit does not itself authorize refund/feature/timeline wording. It still omits what a destructive save overwrites and how expectedRevision conflicts are handled.

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 short sentences, purpose front-loaded, followed by validation and default-behavior rules with no filler. Slightly more could be said about the destructive/concurrency behavior, but 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?

An output schema exists, so return values need not be described, and the semantic caveat about what a limit does not authorize is valuable. But for a destructive 11-parameter write with 0% schema coverage, the description is silent on revision/concurrency handling, required deskId, and overwrite semantics, leaving real gaps.

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

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

Schema description coverage is 0% across 11 parameters, so the description must carry the burden; it does explain the trickiest ones (maxTier vs tierLadder, the three allow*Promise defaults, and channel scope). It leaves deskId, name, notes, status, and expectedRevision entirely undocumented, so compensation is only partial.

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 ('Store the escalation limit ... for one channel') and scopes it to a single channel, which distinguishes it from the read-side sibling list_escalation_limits. It does not explicitly name an alternative or contrast itself with save_approved_commitment/save_refund_rule, so it falls 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?

'The user has explicitly approved' implies a precondition for use, which is useful workflow context. However, there is no explicit when-to-use vs when-not guidance, no mention of the related list_escalation_limits read tool, and no statement about what to do when a limit already exists.

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 destructive and idempotent, and the description is consistent with both, adding meaningful behavior: an approval precondition, that ALLOW grants the wording, and that DENY refuses a refund and records the denial script. It doesn't discuss the effect of re-saving (expectedRevision/locking) or the retired status path, but it adds real context beyond 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?

Four short sentences, front-loaded with the action and the approval precondition, and each sentence carries distinct information. Slightly fragmentary in flow but 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?

An output schema exists so return values need no explanation, and the description covers the semantic heart of decision/remedy/matchTerms. But for an 8-parameter, destructive, revision-guarded mutation with 0% schema coverage, the missing guidance on windowDays, status, and expectedRevision leaves it only partially 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 0% across 8 parameters, so the description must compensate but only partly does: it explains matchTerms' intent, remedy's downstream role, and the ALLOW/DENY meaning of decision. It says nothing about deskId, name, status, windowDays, or expectedRevision, leaving several parameters semantically undocumented.

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 ('Store a refund rule') and adds a key qualifier: the rule must be explicitly user-approved. This clearly separates it from read-side siblings like list_refund_rules. It stops short of explicitly naming an alternative, so it lands at 4 rather than 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 domain constraints on when a rule is valid ('matchTerms must name a specific situation', 'the word refund alone is not a rule'), which is genuinely useful routing logic. However, it never says when to call this versus save_approved_commitment or save_escalation_limit, nor states prerequisites like an existing desk.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is well covered. The description adds meaningful behavioral context: an empty result means no approved answer exists, and the agent is explicitly told not to invent one. It also hints at pagination via 'Page with offset'.

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 short sentences, front-loaded with the purpose and followed by the most important caveat (empty result and no invention) then pagination. The phrasing 'Page with offset' is slightly clipped but still compact and waste-free.

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?

An output schema exists, so return values need not be explained, but the description fails to document the required 'deskId' parameter and the 'includeRetired' behavior. For a four-parameter tool with zero schema descriptions, this leaves an agent without enough information to call it correctly in all cases.

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

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

Schema description coverage is 0%, so the description must carry the full burden. It gives semantics for 'query' (topic, question, answer text) and 'offset' (paging), but completely omits the required 'deskId' parameter and the 'includeRetired' flag, leaving two of four parameters undocumented anywhere.

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 ('Look up') and resource ('approved answers') and even specifies the fields searchable (topic, question, answer text). It clearly distinguishes this read-only search from the write sibling save_approved_answer and from the commitments-related list tools.

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

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

Usage is implied by the purpose statement, and the note about empty results gives some guidance on interpreting output. However, there is no explicit when-to-use versus alternatives (e.g., save_approved_answer or list_approved_commitments) and no stated prerequisites or exclusions.

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