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

Annotations declare readOnlyHint=false / idempotentHint=false / destructiveHint=false, so the mutation profile is already covered. The description adds the identity-resolution behavior and the follow-up step, but says nothing about what happens if the handoff is already claimed, not pending, or how failures surface for a non-idempotent state transition.

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: the core action leads, the conditional parameter rule follows, and the next-step tool is last. 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 2-parameter state-transition tool with no output schema, the description covers purpose, the conditional identity rule, and the follow-up call. It is missing only edge-case behavior (non-pending/already-claimed handoffs), which is a minor gap given the annotations already signal a non-idempotent write.

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 both parameters (handoff_id, agent_name) are fully documented in the schema. The description's rules for agent_name restate the same requirement already in the schema field description, adding little beyond the baseline.

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

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

States a specific verb+resource ('Claim a pending handoff and record its acceptor'), which is clearly distinguishable from create_handoff, get_handoff and delete_handoff. It does not explicitly contrast itself with those siblings, but the transition semantics 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?

Provides a concrete rule for when agent_name is needed (family credentials, unbound/stdio broadcast claims) versus bound tokens. It also names the required follow-up tool (complete_handoff), giving the agent the workflow context. No explicit exclusion of alternatives such as complete_handoff, but the sequencing is 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 declare non-read-only, non-destructive, non-idempotent, but the description adds the genuinely useful behavior: near-duplicates are returned rather than created unless `force` is set. It also flags that `author` is required. Return format and any auth/rate constraints are left unstated, keeping it out of the top band.

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 tight sentences with zero filler; the purpose, scope constraint, and duplicate-handling caveat are all front-loaded. Every sentence carries distinct information an agent needs before calling.

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-parameter mutation tool with no output schema, the description covers the essential decision points: what belongs here, the required author, and duplicate semantics. It omits what a successful call returns and how the scoping parameters (client_slug, cross_client_safe) interact, though the schema covers those fields.

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

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

Schema description coverage is 75%, so most parameters are already documented (notably `force`, whose conditional use is fully explained by the schema). The description's mentions of `author` and `force` largely restate structured data, adding little syntax or format meaning beyond it. 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 ('Add a knowledge entry') and immediately scopes the content to cross-agent material (gotchas, safety/compliance rules, verified patterns, vendor behaviour). The scope statement cleanly separates it from siblings like update_knowledge and delete_knowledge, which an agent can tell apart 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 explicit inclusion criteria ('Cross-agent only...') and an explicit exclusion plus redirect ('Host-local lessons belong in your own docs, not here'). It stops short of naming alternative tools (e.g. update_knowledge for edits), so it is clear context rather than full routing.

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), and the description adds real behavioral detail beyond them: the 20/5 result caps, the meaning of `has_more`, the compact form of notify-class entries, and the non-obvious rule that self-filed accepted handoffs become locks tracked in `self_claims_held` rather than being listed. It stops short of describing per-item fields in full, so a 4 rather than 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?

The scoping and caps are front-loaded and the follow-up routing comes immediately after, which is good structure. It is dense and leans on domain shorthand ('locks', 'self_claims_held', 'notify-class') that a first-time caller must parse, keeping it from a 5.

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?

There is no output schema, so the description carries the return-value burden and does so: it names the subsections, their caps, the `has_more` sentinel, and `self_claims_held`. Combined with the annotation-covered safety profile and the complete single-parameter schema, an agent has everything needed to call and interpret this 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?

With a single parameter at 100% schema description coverage, the schema already documents the format, character class, and examples for `agent_name`, so the baseline is 3. The description only restates that it is a free-form slug and that it filters handoffs addressed to you, adding little 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?

The description states a precise verb+resource framing ('pending-work query' returning 'open action handoffs addressed to you or to nobody in particular') with the exact sectioning and caps. It is clearly distinct from siblings like list_handoffs and get_handoff, naming each where relevant.

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 triggering situation (checking pending work), routes the agent explicitly when results are truncated ('has_more ... use list_handoffs for the rest'), and spells out the follow-up chain ('Next step is get_handoff for the full body, then accept_handoff'). No ambiguity about when to reach for this tool versus its siblings.

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

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

Annotations already declare the important traits (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the safety profile is covered. The description adds real behavioral context by explaining that commit_hash enables a later `mark_merged` transition, but it says nothing about repeat-call behavior, permissions, or whether a completion can be undone — notable gaps given idempotentHint=false.

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

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

Two tightly written sentences, front-loaded with the action and followed by the optional-parameter consequence. Slight redundancy with the schema's commit_hash wording costs it the top mark but nothing is padded.

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 state-transition tool with no output schema, the description covers the action, the optional parameter's downstream purpose, and names the follow-up tool. Missing only edge-case behavior (already-completed handoffs, failure modes), which would round it out.

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 both parameters are already documented in the schema, which sets the baseline at 3. The description's 'commit_hash records the work ref (typically a git SHA)' essentially restates the schema text rather than adding new syntax, format, or validation detail.

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 ('Mark a handoff as completed') and names the related sibling 'mark_merged' that later flips the same handoff to merged, so the agent can place it in the lifecycle. It stops short of distinguishing itself from the closer cousin 'accept_handoff', which is a plausible alternative an agent might otherwise confuse it with.

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 context for invoking it and explicitly routes the later stage of the workflow to `mark_merged`, which is useful condition-based guidance. There is no explicit 'when not to use' or guidance against calling this on an already-completed handoff.

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 non-read-only, non-idempotent, non-destructive writes, and the description adds real value beyond that: 'this is sufficient notification' (no separate notify call needed) and the 7-day pruning of notify-category handoffs. It stops short of describing the return value or failure modes.

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 dense clauses, zero filler, with the core purpose front-loaded and the reply-routing tip positioned as the closing actionable instruction.

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 write tool with no output schema, the description covers notification semantics, category persistence, and threading. It omits what the caller gets back (handoff ID) and any error/permission conditions, which is a minor gap given rich annotations and full 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 100%, so the schema already documents every parameter in detail. The description restates category semantics and adds the threading rationale for in_reply_to, but largely mirrors schema content, so the 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 ('Create a handoff for another agent') and immediately scopes the two behavioral modes (action vs notify). An agent can distinguish this from siblings like accept_handoff or complete_handoff without inspecting 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 explicit when-to-use guidance for the two categories and, crucially, routes replies: 'Replying? Pass in_reply_to to stay in the existing thread instead of opening a parallel handoff' names the alternative behavior. It does not clarify when to prefer this over add_knowledge or other siblings, so it falls short of full alternative 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the deletion is audited and audit_log retains a tombstone containing the handoff id, deleter identity, sender, recipient, title, and status. It does not state whether related replies or dependent records are also removed, which is the main 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, zero filler, with the irreversible nature of the operation front-loaded ahead of the audit side effect. 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 one-parameter destructive tool with annotations covering safety, the description covers the two things an agent most needs: that the delete is permanent and what survives it. It stops short of explaining cascading effects (replies to the handoff) or permission requirements, which would make it fully 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 100% for the single handoff_id parameter, so the schema already documents the UUID format. The description only restates "by ID" and adds no syntax or format detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource ("delete a handoff by ID") and immediately qualifies the semantics as a hard, permanent delete, which is the key distinction an agent needs. The resource name and the hard-delete qualifier separate it from the sibling delete_knowledge and from complete_handoff 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?

There is no explicit when-to-use, when-not-to-use, or alternative guidance. Given siblings like complete_handoff, accept_handoff, and mark_merged, an agent would benefit from knowing when deletion is the correct action versus closing a handoff out normally, and the description never addresses that choice.

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 readOnlyHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that: it does not say deletion is irreversible, whether dependent records are affected, or whether a missing ID is an error.

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?

One short sentence, front-loaded with the verb and resource, with zero filler or redundancy. Nothing could be removed without losing meaning.

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 destructive delete whose safety semantics are fully carried by annotations and whose parameter is fully documented by the schema, the description is essentially sufficient. A minor gap is the absence of any note about irreversibility or outcome, though destructiveHint partly compensates.

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 'id' parameter (UUID format) is fully documented in the schema. The description only restates that the ID identifies the entry, adding no syntax or format detail beyond the schema — the baseline 3 for full coverage 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 (Delete) and resource (knowledge base entry) plus the lookup key (by ID), which clearly separates it from add_knowledge and update_knowledge. It does not explicitly name a sibling or a scope boundary, 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?

There is no when-to-use or when-not-to-use guidance, and no prerequisites (e.g. permission requirements) are mentioned. Usage is only implied by the verb 'Delete', matching the calibration level for 'no when-to-use, no prerequisites'.

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=false and destructiveHint=false, so the safety profile is fully covered. The description adds only that the full body and context are returned, which is useful payload context but does not describe error behavior for an unknown UUID or whether the response is paginated.

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?

One sentence, front-loaded with the verb and resource, and it also front-loads the key constraint (full UUID) and the payload. Nothing is padded or 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 single-parameter read tool whose annotations cover the safety profile, the description is nearly sufficient. The only gaps are routing to siblings and failure behavior on an invalid or missing UUID, which are minor for this level of complexity.

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

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

Schema description coverage is 100% and the single parameter is fully documented as 'Full handoff UUID'. The description's 'by its full UUID' restates the same requirement without adding format, sourcing, or error-handling detail, so this sits at the schema-covered baseline.

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

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

States a specific verb (get) and resource (one handoff) plus the lookup key (full UUID) and the payload returned (complete body and context). It is clear on its own, but never names the sibling it is distinct from (list_handoffs, search_bus), so an agent gets no explicit routing signal.

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 phrase 'by its full UUID' hints you need a known identifier rather than a search, which distinguishes it loosely from list_handoffs and search_bus. There is no explicit when-to-use, when-not-to-use, or prerequisite statement.

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 no behavioral context beyond that — it omits the default action-only view, the compact=true truncation default, and result ordering — so it does not clear the higher bar.

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, purpose front-loaded and the actionable hint second. Nothing is wasted or 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 read-only list tool with a fully documented schema and no output schema, the essentials are covered. However it leaves the default result shape (action-only, truncated bodies) and the distinction from search_bus/list_replies_to_me to the agent's inference.

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 seven parameters (limit clamping, status values, compact, category, agent slugs, include_notify) are already fully documented. The description's status='pending' example is a minor reinforcement of existing schema content rather than new meaning. 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+resource ('List handoffs') plus the filtering affordance, which is clear on its own. It does not distinguish itself from siblings like get_handoff, list_replies_to_me, or search_bus, 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?

Offers one concrete usage hint ('Use status="pending" to see what needs attention'), which gives implied context. It never states when to use this over get_handoff (single item) or search_bus (free-text search), so the alternative-selection guidance is absent.

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, and non-destructive behavior, so the safety profile is covered. The description adds genuine value by exposing the underlying query semantics (the `in_reply_to` ↔ `from_agent` join) and the timestamp-based filtering behavior, though it says nothing about pagination 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 tight sentences, front-loaded with the core purpose followed by precise semantics. Every sentence earns its place with no redundancy or 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?

With no output schema, the description correctly explains what the tool returns (handoffs whose `in_reply_to` references one of yours). For a simple, read-only list tool this is nearly complete, though it omits default result count and ordering, which are relevant to the caller.

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 all three parameters are already documented in the schema, including `since` and `limit`. The description largely restates the `since` semantics rather than adding format or syntax 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 states a specific verb (List) and resource (handoffs) with a precise scope: only replies to handoffs you sent. The second sentence defines the exact join condition (`in_reply_to` referencing a handoff with your `agent_name` as `from_agent`), which clearly distinguishes it from the sibling `list_handoffs`.

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 scoping (use when you want replies to your own handoffs), but the description never explicitly names alternatives like `list_handoffs` or `search_bus`, nor states when not to use it. A reader can infer the context but gets no 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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description goes beyond this by specifying the exact idempotency semantics ('idempotent on identical merge_commit; refuses to overwrite a different one'), which is the concrete behavior an agent needs to predict outcomes on repeat calls.

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, front-loaded with the action, then the calling context, then the idempotency edge case. No filler, though the calling-context sentence could be trimmed without loss for a purely mechanical caller.

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 2-required-param mutation with full schema coverage and annotations carrying the safety profile, the description covers what changes, when it is invoked, and how repeat calls behave. No output schema exists, but the state transition is plain enough that return details are not critical.

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 both handoff_id and merge_commit are already documented, and merge_commit's 'free-form — any opaque identifier works' is captured in the schema. The description adds no format or syntax detail beyond what the schema provides, 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+state change: 'Flip a handoff to status=merged and record the merge commit.' This is clearly distinguishable from siblings like complete_handoff, accept_handoff, or create_handoff, which represent different lifecycle transitions.

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 usage context: 'Typically called by an integrator script after the bundle containing the handoff's commit_hash lands in main.' This explains the trigger condition well, but never names a sibling alternative or an explicit when-not-to-use case (e.g., vs complete_handoff).

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 covered. The description adds the meaningful trait that an empty query flips the tool into a browse mode and that multi-table defaults differ, but says nothing about result ordering, scoring, or what withholding of cross-client results looks like.

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 dense, zero-padding sentences with the core action front-loaded. It is arguably too terse in places ('Set tables param for multi-table'), trading a little clarity for compactness, but no sentence is wasted.

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-parameter, multi-mode search tool with no output schema, the description covers modes and browse behavior but not result shape, ranking, or how cross-client withholding resolves. Adequate as a starting point, incomplete for an agent that needs to interpret output.

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 every parameter (including mode values, limit clamping, and category being browse-only) is already documented in the schema. The description restates mode values and the tables param without adding format or interaction detail beyond what the schema provides — baseline 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 (Search) and resource (knowledge and/or handoffs), and names the mode dimension. It never distinguishes itself from siblings like list_handoffs or get_handoff, so an agent must infer that this is the ranked/query-based retrieval path rather than the enumerate-one path.

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 conditions for the browse path ('Empty query or "*" browses recent entries') and for multi-table via the tables param, but offers no guidance on when to choose this over list_handoffs/get_handoff, nor any exclusions. Usage is implied by mode semantics rather than stated as routing advice.

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 is a non-read-only, non-destructive, non-idempotent, non-open-world mutation, so the safety profile is covered. The description adds the useful patch semantic that unspecified fields are left untouched, but says nothing about what tags do (replace vs append), what the call returns, or whether auth/scoping is required. Annotation-vs-description is consistent, so no contradiction.

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

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

Two tight sentences with the identity/target information front-loaded and zero filler. 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 7-parameter mutation with no output schema and 43% schema coverage, the description should say more about return behavior, tag replacement semantics, and any authorization requirements. It adequately covers the update model but leaves real gaps an agent would want filled.

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 43%: id, verified, and cross_client_safe are documented in the schema, while tags, title, content, and category carry only self-evident names. The description's 'only provided fields are updated' clarifies overall patch behavior, but it adds no per-parameter meaning (e.g., whether tags overwrite the existing set), so it only partially compensates for the coverage gap.

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 ('Update an existing knowledge base entry by ID') and makes the lookup key explicit. It does not name or differentiate itself from siblings like add_knowledge or delete_knowledge, but the intent 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?

There is no statement of when to reach for this tool versus add_knowledge, delete_knowledge, or search_bus, and no prerequisites or permission notes. 'Only provided fields are updated' is behavioral semantics, not usage routing, so the agent gets no decision guidance.

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