UNITARES

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

Annotations already declare readOnly/idempotent/no-destructive, and the description layers on genuinely additive behavior: which proofs bind the read (client_session_id, X-Session-ID, continuity_token) vs. an unbound self-read, the identity_mismatch case, and the identity_assurance.caller_proven=false marking on inferred sessions. This is well beyond the annotation surface.

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 purpose is front-loaded, but the body is a dense wall of run-on sentences with heavy parenthetical nesting and semicolon-chained clauses. The EISV glossary is useful, yet the identity-binding prose could be tightened considerably without losing 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?

With no output schema, the description does the heavy lifting for returns: it defines E/I/S/V ranges and semantics, next_action recovery, and what each verbosity tier yields. It stops short of enumerating verdict/basin/mode values themselves, relying on the server to attach meanings.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: verbosity tiers ('standard adds mode and basin with their meanings'; 'full' is an alias for lite=false) and that continuity_token is same-process-only, 'never a cross-process resume.' The lite/verbosity precedence is clarified too.

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 states a precise verb+resource ('Read your current governance state and verdict') and immediately bounds scope with negations ('without running a cycle, writing, or minting an identity'). It is explicitly distinguishable from siblings like sync_state and get_governance_metrics, which it names.

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 names alternatives and their conditions: sync_state 'also logs work and returns proceed or pause' vs. this pure read, and get_governance_metrics as the raw-payload route. It also explains the recovery path ('next_action says how to recover') and the binding preconditions for a valid read.

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

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

Annotations only flag readOnly=false, openWorld=true, idempotent=false; the description adds far more: the thorough lane's strong-model cross-family routing, the cloud_allowed + operator-extension prerequisite, the degraded fallback semantics, the bound-identity requirement, the audit event_type and hash-only visibility, and that success mutates governance state. This is rich disclosure 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?

Front-loads the core purpose and the key alternative, then layers prerequisites and side effects. Dense and information-rich, though the middle sentences are tightly packed with clauses; nothing is truly wasted, but it borders on overload for a single paragraph.

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

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

No output schema, yet the description covers the return shape (advisory result + policy outcome, diagnostics with route and provenance under full), the failure modes, the identity prerequisite, and the side effects. An agent has everything needed to invoke it correctly or fall 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 coverage is 100%, so baseline is 3, but the description adds real parameter meaning the schema lacks — that thorough needs privacy='cloud_allowed' plus an operator extension and otherwise fails unless allow_degraded=true, and that allow_degraded never weakens the requested privacy. It does not elaborate on purpose, response_mode, or the session/token params 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?

Names a specific action and resource ('send a brief, get back advisory model evidence') and explicitly separates itself from the sibling that produces verdicts ('never a governed verdict — request_review produces that'). An agent can distinguish consult from request_review, call_model, and delegate_inference without opening any 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 explicit when-to-use (advisory model help) and when-not (governed verdicts → request_review; explicit provider/host/model/timeout control → call_model or delegate_inference). Also names the preconditions (privacy=cloud_allowed + operator extension, else allow_degraded=true) and the identity requirement.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context beyond them: the lite=false default means an unqualified call returns the full record, and lite=true downgrades to a summary. It doesn't cover error behavior for an unknown tool_name, which keeps it from a 5.

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

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

Four sentences, each load-bearing: what is returned first, then sibling routing, then default-mode behavior, then router nuance. No filler and the most decision-relevant information is front-loaded.

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 enumerates the return payload and the mode-dependent variations. Combined with 100% schema coverage and existing annotations, an agent has everything needed to call this correctly for a read-only inspection 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 100%, so the baseline is 3, but the description adds genuine meaning: it clarifies that lite=true yields a 'first-line-plus-key-parameters summary' and that action narrows the response to that action's parameters. The remaining params (agent_id, continuity_token, client_session_id) are left to the schema, but the mode-defining params are well covered.

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 (Return) and resource (one named tool's record) and enumerates exactly what the record contains: description, stability tier, operation, examples, and input schema. It is clearly distinguishable from the sibling list_tools, which returns many tools rather than one.

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

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

Explicitly routes the agent to alternatives with conditions: list_tools(lite=true) for the compact index, list_tools(lite=false) for rich catalog metadata. It also explains what an unqualified call returns and how action=... behaves on a consolidated router, leaving nothing to inference.

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

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

Adds substantial context beyond the annotations: it explains the side effect that justifies readOnlyHint=false ('Not a plain read… persists a new agent and reports on that one, marked caller_proven=false'), warns that a cosmetic name never looks an agent up, and clarifies continuity_token is per-process proof whose cross-process use 're-opens silent resurrection'. This is exactly the non-obvious behavior an agent needs. No contradiction with the provided hints.

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

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

Purpose is front-loaded in the first sentence, and nearly every clause carries distinct behavioral information. It is a dense single block, though, with compressed jargon ('silent resurrection', 'co-located binding') that costs readability for an 8-parameter dual-mode tool.

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

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

For a complex identity tool with 8 optional params and no output schema, the description covers the hard parts — minting gate, cosmetic vs. identity fields, ownership-proof token, and a hint at the reported marker (caller_proven=false). It omits guidance on resume/model_type/agent_uuid and any return-shape detail, but those are largely covered by the 100%-covered schema.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter interaction semantics the schema does not carry: the gating rule keyed on presence/absence of proof arguments, and the note that name= is cosmetic and thread-safe guidance ('Thread uuid across tools, not this'). That is genuine value above the schema.

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

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

States a specific dual purpose: 'Resolve which agent this MCP session is bound to, or set a cosmetic display name.' The verb+resource pair is concrete and the two modes are distinguishable. Sibling differentiation is weak, though — it points to 'onboard(force_new=true)', which is not among the listed siblings, and never contrasts with the actual sibling 'start_session'.

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 branching guidance: a call with no proof argument is gated to a fresh mint, a call with only a cosmetic name= skips the gate and can infer a co-located binding, and pass client_session_id to get your own back. It routes to an alternative ('onboard') for a fresh process. It stops short of an explicit 'use this instead of X when…' rule against the real sibling set.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: the two response modes and their contents, and the important operational fact that the tool can be called before identity binding.

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

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

Front-loaded with the core purpose and scoping, and most sentences carry routing value. Slightly dense with several chained instructions, but there is little outright waste.

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

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

For a 10-parameter read-only catalog tool with no output schema, the description covers mode selection, scope, and the identity precondition adequately, and routes to the correct follow-up tools. It does not describe pagination or volume limits, a minor gap given the breadth of the catalog.

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 10 parameters are already documented, and the schema even explains the lite default. The description largely restates the lite semantics and adds only marginal detail (workflows, relationships, direct-advertisement status) not covered elsewhere, so baseline 3 applies.

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

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

States a specific verb ('Discover') and resource ('complete governance capability catalog'), and immediately clarifies it includes names omitted from the initial progressive tools/list advertisement. It is clearly distinguished from sibling tools describe_tool and use_tool, which it explicitly references.

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 branching guidance: use the default lite=true for the compact handshake, lite=false for the richer catalog, describe_tool for one capability's parameters, and use_tool to invoke capabilities missing from the initial listing. It also states the precondition that it is callable before an identity is bound.

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

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

Adds substantial behavior beyond the annotations: prediction_id is consumed on first use and TTL-bound (~1 hour), a bound or explicit agent_id is needed, it refuses under strict identity from an ephemeral session, and provenance cannot be self-attested (verification_source forced, provenance keys stripped). This is exactly the write-safety and state-mutation context an agent needs, and it is consistent with idempotentHint=false and destructiveHint=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?

Front-loads purpose, then layers binding, TTL, identity, and provenance rules in a compact sequence where each clause carries real information. It is dense and occasionally hard to parse (the outcome_event/raw_governance sentence), 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?

Appropriately complete for a 14-parameter mutation tool with no output schema: it covers binding lifecycle, identity requirements, provenance constraints, response-mode effects, and points to describe_tool for EISV field definitions. Nothing critical to invoking it correctly appears missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns above baseline by explaining why prediction_id exists (bind to a check-in's confidence), how response_mode/include_semantics gate the digest envelope and raw payload, and the forced verification_source. One minor wrinkle: description says prediction_id comes from a sync_state reply while the schema says process_agent_update response.

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 ('Record a measurable outcome') plus the reason it exists ('pair it with this agent's EISV snapshot so verdicts can be graded'). It explicitly differentiates from siblings by naming 'store_finding for durable knowledge' and 'outcome_event is the canonical twin', so an agent can distinguish it without opening another 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 routing context: pass prediction_id from a sync_state reply, use store_finding for durable knowledge, and it clarifies the relationship to the outcome_event twin. It stops short of a crisp 'use this when X, use outcome_event when Y' rule, leaving the digest-envelope vs raw-payload distinction somewhat implicit.

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

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

With annotations already declaring readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, the description goes well beyond them by disclosing the identity requirement, the SESSION_EXISTS refusal, the waiting_input skip behavior, and the one-call vs two-call flow. These are exactly the mutation-state traits an agent needs to predict outcomes.

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?

Dense but front-loaded — the lead sentence establishes the core action before qualifications. The final clause about dialectic and consult is somewhat terse and assumes familiarity, costing a point.

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 9-parameter, non-idempotent, open-world session tool with no output schema, the description covers prerequisites, failure modes, and the alternate flow well. The residual gap is how the referenced dialectic/consult actions map onto this tool versus the sibling consult 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 100%, so the baseline is 3. The description does add real meaning for issue_description and use_brief_as_thesis (thesis reuse semantics), but several schema descriptions reference an 'action' parameter that does not exist in the schema, leaving the parameter model partially unclear.

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 ('Open a governed, on-record review session for this agent') and immediately distinguishes the mode from related capabilities, noting that dialectic advances an open session and consult yields advisory evidence with no verdict. An agent can tell this is the session-opening entry point rather than an advisory or continuation tool.

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

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

Gives explicit when-to-use conditions: issue_description is reused as the thesis by default so a single call can reach a verdict, and use_brief_as_thesis=false selects the two-call form. It also names prerequisites (session-owned registered identity) and the conditions that route the agent elsewhere or fail (SESSION_EXISTS while active, skipped when waiting_input).

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

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

Annotations declare readOnlyHint=false without explaining why; the description supplies exactly that missing context, disclosing that every successful search appends a knowledge_read audit row naming the reader plus a redacted query copy. It also documents the visibility side effect that archived/cold rows are hidden unless status/include_archived/include_cold are set, which is behavioral information the annotations cannot convey.

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, front-loaded with purpose then caveats, side effects, and routing, with no filler. It is dense rather than bloated, though the 'resolved or closed' clause sits slightly awkwardly against the status enum, which costs a point.

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 25-parameter, no-required, no-output-schema search tool, the description covers the high-risk behaviors: default filtering, the audit side effect, call ordering relative to start_session, and sibling routing. Response envelope modes and pagination are left to the schema, which documents them well, so remaining gaps are minor.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real cross-parameter semantics: the interaction between the default status filter and include_archived/include_cold, and that resolved/closed findings still surface. It does not cover the 25 parameters exhaustively, but it lifts the most error-prone filtering logic above what the schema alone states.

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?

Opens with a specific verb and resource ('Search the cross-agent knowledge graph for prior findings') and explicitly separates itself from the write siblings by naming store_finding and update_finding. An agent can distinguish read-from-search versus add/revise without opening any 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?

States when it applies ('serves unbound callers, so it works before start_session, unlike the writes') and names the alternatives for adjacent operations (store_finding to add, use_tool(update_finding) to revise). The archived/cold exclusion rule and the resolved/closed exception give concrete filtering conditions rather than leaving them to inference.

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

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

Despite annotations covering the safety profile (destructiveHint=true, idempotentHint=false), the description adds substantive behavior: check is a pure no-op, neither resume path runs while a void is active, a refused attempt still stamps recovery_attempt_at, a missing reflection is rejected before that stamp, and the reflection is written to the shared knowledge graph regardless of outcome. These are exactly the non-obvious traits an agent needs.

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

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

Front-loaded with the core action, and virtually every clause carries a distinct behavioral fact rather than filler. It is dense and multi-clause, which slightly taxes readability, but nothing is redundant.

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

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

For a 7-parameter, mutation-class tool with no output schema, the description covers triggers, mode selection, constraints, and side effects. The one gap is that it does not describe what action='check' returns diagnostically, which an agent calling the default mode would benefit from knowing.

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 baseline is 3, but the description adds requirements beyond the schema: the reflection minimum of 20 characters and its graph-recording side effect, and the risk caps attached to quick vs review. It also reinforces that continuity_token is a same-process-only proof, matching the schema hint.

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 ('Lifts a pause or other hold on your own agent') with immediate scope narrowing ('your own agent'). It also names the routing alternative operator_resume_agent, so an agent can tell it apart from the resume tools 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 concrete mode semantics (check = no state change, quick = fast resume at 0.40 risk cap, review = 0.65 cap plus a 20+ character reflection) and a clear exclusion ('To resume an agent you do not own use operator_resume_agent'). Slightly implicit on the top-level trigger ('use this when your agent is paused'), which keeps it from 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 only supply generic hints (readOnly=false, idempotent=false, destructive=false). The description goes well beyond them, disclosing the force_new defaulting/refusal path under strict identity, the parent_agent_id succession rule (live parent rejected as coincidental), and response_mode='full' retaining the raw payload under raw_governance.

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

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

Front-loaded with the purpose, but the body is a chain of semicolon-joined clauses mixing identity rules, lineage rules, and response modes, making it hard to scan. Information density is high, but structure and readability suffer.

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 17-param, zero-required identity bootstrap with no output schema, the description covers the essential call path and the critical failure modes (defaulting, refusal, lineage rejection). It omits the response envelope's full contents, but names the two key fields to retain (client_session_id, agent_uuid).

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 baseline is 3. The description still adds meaning the one-line schema entries lack: the interactive semantics of force_new (defaulted-or-refused, never resumed onto another uuid), the parent_agent_id validation outcome, and where the uuid surfaces (agent_uuid).

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: 'Register this process-instance and mint its agent identity,' and names siblings it differs from ('Use identity to inspect or rename an existing binding', 'onboard is the canonical twin'). The dense jargon slightly obscures the plain purpose, but the core action 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?

Gives concrete routing: use force_new=true, a bare call is defaulted or refused, use identity for inspect/rename, and onboard is the canonical twin. Covers when-to-use and some when-not, though it never gives a clean 'prefer onboard unless X' rule.

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?

Goes well beyond annotations: discloses that every call mints a NEW discovery (non-idempotent), a 20-findings/hour budget, the auth gating on high/critical severity, the anonymous-writer fallback for low/medium, and the required-summary quirk that contradicts the schema's all-optional marking. This is exactly the behavioral context an agent needs.

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?

Dense but front-loaded: the core write action and return value come first, followed by constraints in descending priority. Every clause carries information, though the run-on sentence packing auth, fallback, alternatives, and budget is heavier than ideal.

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 13-parameter mutation tool with no output schema, the description covers the return value, auth requirements, rate limits, idempotency behavior, and sibling routing. An agent has everything needed to call it correctly without opening other sources.

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 baseline is 3. The description adds real semantics on top: summary is required at call time despite the schema, and agent_id should be left unset because the bound session is the writer. Severity gating is also explained, though per-field syntax details stay in the schema.

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

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

States a specific verb and resource ('Write one new durable finding into the cross-agent knowledge graph') plus the return value ('get back its discovery_id'). It clearly distinguishes itself from siblings by naming search_shared_memory, update_finding, and record_result as different operations.

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: search_shared_memory first, revise via use_tool(tool_name='update_finding'), and the boundary against record_result ('discovery, root cause or correction' vs 'task, tool or test outcomes'). Both when-to-use and which-alternative are spelled out.

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 only cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds substantial behavior beyond that: state advancement and persistence, identity auto-binding and strict-identity refusal, audit-event appending by the preview twin, and the digest-vs-raw envelope tradeoff with response_mode='full'. It does not spell out permission/auth requirements or idempotency semantics, which keeps it below a 5.

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

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

Front-loaded with the core action-and-return, then alternatives and envelope details. It is dense and paragraph-shaped with several clauses packed together, but each clause carries routing or behavioral information rather than 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?

For a 23-parameter, zero-required, no-output-schema tool, the description covers the decision semantics, the returned fields (verdict, named reason, prediction_id), identity binding, response-shape modes, sibling routing, and defers EISV field definitions to describe_tool. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description nonetheless adds real meaning: that prediction_id is returned only when confidence is supplied (a linkage the schema doesn't state), and that response_mode='full' surfaces the raw payload under raw_governance rather than just changing envelope shape.

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 ('Record a work check-in') and outcome ('get a governance decision ... proceed or pause with a named reason'), and explicitly distinguishes itself from siblings: simulate_update previews without advancing, check_working_state reads without writing, process_agent_update is the canonical twin. An agent can pick this apart from adjacent tools without opening a schema.

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

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

Explicit routing: use record_result to grade a check-in later, start_session when strict identity refuses, simulate_update to preview, check_working_state for the current verdict. Also states the first-call auto-bind behavior and the one condition (strict identity) under which it fails.

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, readOnlyHint=false, openWorldHint=true, and non-idempotent, so the risk profile is covered. The description adds meaningful context beyond that: the target's own identity, validation, authorization, timeout and response middleware all run, so this gateway is not a privilege escalation path. It stops short of describing error or failure behavior.

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

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

Four sentences, front-loaded with the action and the prerequisite chain, then the safety clarification and the recursion exclusion. The middleware enumeration is slightly long but each clause carries a distinct behavioral fact worth keeping.

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

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

No output schema exists, so the description should orient the agent on return expectations, which it only gestures at implicitly. For a five-parameter gateway with nested arguments, it otherwise covers prerequisites, delegation semantics, and the key failure mode (recursive refusal) adequately.

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% with all five parameters documented, so the baseline is 3. The description only reinforces that arguments must be built from describe_tool output and that tool_name must be the exact name from list_tools, adding marginal value over the schema's own field descriptions.

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: invoke one public capability discovered via list_tools. It also carves out exactly what it is not ('a discovery gateway, not an authorization bypass'), which distinguishes it from siblings like list_tools, describe_tool, and the session 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?

Explicit sequence: find the name with list_tools, inspect arguments with describe_tool, then pass the argument object here. It also states an exclusion — it refuses recursive use_tool calls — so the agent knows both when to use it and one case where it will not work.

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