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 read-only, idempotent, non-destructive behavior, and the description goes further by prescribing the required downstream action for each verdict (do not invent a substitute, use only sayOnly wording, escalate to human review). That is genuine behavioral context beyond the annotations, though it doesn't cover failure modes or what happens with an unknown proposal.

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 packed sentences with the purpose front-loaded and the verdict semantics following. Every sentence adds information, though the density means a reader must parse the conditional behaviors carefully.

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 supplies the crucial interpretation of REFUSED vs APPROVED plus the 'sayOnly' field's role. The remaining gap is desk scoping and edge-case behavior, which is minor given the structured output coverage.

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

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

Schema description coverage is 0%, so the description carries the burden. It effectively explains 'kind' (refund/feature/timeline) and the optional 'channel' (also enforces the escalation limit), and 'proposal' is inferable from context, but 'deskId' scope and any format expectations are left entirely 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?

The opening sentence gives a specific verb (decide) and resource (whether a proposed refund/feature/timeline is in the approved set), which maps cleanly to the 'kind' enum values. It distinguishes itself from list/save siblings, and the closing line hints at its relationship to escalation checking, though it never names evaluate_escalation 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?

Usage is implied through the outcome semantics (REFUSED -> draft for human review; APPROVED -> use sayOnly), which tells the agent what to do with the result. However, it never states when to choose this tool over list_approved_commitments or evaluate_escalation, and there are no exclusions, so the routing guidance is only partial.

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

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

Annotations already declare a safe, idempotent, closed-world read, so the bar is lower. The description adds genuine behavioral context beyond them: the meaning of a REFUSED result and the hard constraint that granting permission does not authorize the exact wording, which must go through evaluate_commitment. It does not discuss what the non-REFUSED verdicts look like, but the output schema covers returns.

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

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

Three tight sentences with the decision purpose front-loaded, the REFUSED consequence in the middle, and the evaluate_commitment dependency last. Every sentence earns its place and nothing is repeated from the schema or annotations.

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

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

With an output schema present, return values needn't be described, and the description does cover the decision semantics, the refusal path, and the sibling dependency. The remaining gap is the undocumented deskId/channel inputs, which matters for a 4-parameter tool with zero schema coverage.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. Its opening sentence enumerates exactly the four action enum values (escalate / promise refund, feature, timeline), and 'do not invent a tier' hints at targetTier, but deskId and channel are never explained. Partial compensation at best, so a 3.

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 (decide whether a channel may escalate or promise) and explicitly differentiates itself from the sibling evaluate_commitment by scope: permission here, exact wording there. An agent can route between the two 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?

Gives clear when-to-use context (deciding escalation/promise permission) and a when-not path via the REFUSED outcome: do not escalate, do not invent a tier, draft for human review. It names evaluate_commitment as the required follow-up for wording, though it doesn't state prerequisites such as needing a deskId/channel resolved first.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description layers on policy semantics the annotations cannot express: results are 'evidence, not permission', missing/RETIRED answers must not be fabricated, and REFUSED/gap conditions require human review rather than customer promises.

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 what is retrieved, then immediately graduates to constraints and routing guidance. Five compact sentences carry distinct payloads, though the gap/REFUSED instruction partially restates the 'not permission' framing and could be tightened by one clause.

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 structure need not be described, and the annotations plus description jointly cover safety and the agent's decision workflow. The remaining shortfall is the unexplained limit parameter and what 'selected' means in selection terms, but the operational picture is largely complete.

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

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

Schema description coverage is 0%, so the description is the only place parameter meaning could live, yet it never explains deskId, question, or limit. 'Selected approved answers' loosely implies the limit controls how many answers are returned, but the uuid desk scoping and the question text constraints (max 500 chars) are left entirely implicit.

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

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

Specific verb and resource: retrieves selected approved answers for a customer question plus the desk's approved refund rules, commitments, and escalation limits. This aggregated bundle is clearly distinguishable from siblings like search_approved_answers, list_refund_rules, and list_escalation_limits, which each return a single artifact class.

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

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

Explicit routing: 'Call evaluate_commitment before promising a refund, feature, or timeline' names the alternative and the triggering condition. It also states the fallback behavior (draft for human review when tools fail, return gaps, or REFUSED), which tells the agent when not to proceed.

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 destructiveHint=true and idempotentHint=true, but the description adds real value by explaining the mechanism behind them: identical retries stay on the same revision, and content changes must be guarded with expectedRevision from a previous read. It stops short of saying what a revision overwrites, whether the previous content is recoverable, or any permission requirements.

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

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

Three short sentences, front-loaded with the core action and followed by the two behavioral facts that matter (retry idempotency, revision guard). No filler or restated field names.

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 prose, and the revision/idempotency semantics are covered. However, for a destructive 6-parameter write tool with zero schema description coverage, the description omits the meaning of the status enum (notably RETIRED) and any conflict-handling detail when expectedRevision does not match.

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 burden of documenting them. It only explains expectedRevision (and only its source, not its conflict behavior); deskId, topic, question, answer, and the APPROVED/RETIRED status enum are left entirely to the bare 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 pair (store/revise) and the exact resource (an answer the user has already approved), which cleanly separates it from siblings like save_approved_commitment, save_refund_rule, and save_escalation_limit. An agent can identify the correct tool without opening the schema.

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

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

Gives clear conditional guidance: revising a changed answer requires expectedRevision from a prior read, while identical retries are safe to repeat. It does not name sibling alternatives or state when not to use it, so it falls short of full when/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 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description adds genuinely new behavior: empty results are a valid negative signal, and the no-fabrication/human-review policy. It omits that retired answers are excluded by default (the includeRetired switch), which is a meaningful result-shaping 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?

Four short sentences, each carrying distinct information: scope, empty-result meaning, downstream policy, paging. Front-loaded with the lookup 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?

An output schema exists, so return-shape explanation is correctly omitted, and the description covers the critical downstream policy for a search tool. The main remaining gap is that the required deskId scoping parameter and the includeRetired flag are not described for a schema with no parameter documentation at all.

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%, so the description carries the burden. It usefully clarifies that the query string matches topic, question, or answer text, and that offset drives paging, but the required deskId parameter is never explained and includeRetired's filtering effect is unmentioned, leaving half the 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?

States a specific verb and resource ('Look up approved answers') and narrows the match surface to topic, question, or answer text, which distinguishes it from the write-side sibling save_approved_answer. It does not explicitly contrast itself with the other read siblings (list_approved_commitments, get_desk_context), so it falls just short of 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 concrete operational guidance for the empty-result case ('no approved answer; draft for human review; do not invent one or promise the customer'), which tells the agent exactly what to do next. It stops short of naming when to prefer this over sibling lookups such as get_desk_context or list_approved_commitments.

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