UNITARES

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavioral context beyond them: which proofs are honored (client_session_id, X-Session-ID, verified continuity_token), the fallback to an unbound self-read with next_action recovery, identity_mismatch handling, and identity_assurance.caller_proven=false on inferred sessions. This is well beyond what the safety hints 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?

Core purpose is front-loaded, but the body is a dense wall of run-on clauses mixing auth rules, routing, verbosity tiers, and EISV field definitions into long semicolon chains. It is information-rich but hard to scan, and the EISV definitions and agent_id note are not clearly separated from the call-critical instructions.

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

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

With no output schema, the description carries the return-value burden and mostly meets it, documenting next_action, identity_assurance, raw_governance contents, basin/mode, and EISV field meanings. Gaps remain around the overall response envelope, but it is complete enough to call the tool correctly across its verbosity tiers.

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%, establishing a 3 baseline, but the description adds real meaning: verbosity='standard' adds mode and basin with meanings under raw_governance, verbosity='full' is aliased to lite=false, and verbosity takes precedence over lite. It also explains the EISV field semantics that the schema never touches, exceeding what the schema provides.

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

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

States a specific verb and resource — 'Read your current governance state and verdict' — and immediately bounds scope with 'without running a cycle, writing, or minting an identity.' It distinguishes itself from sync_state (which logs work) and get_governance_metrics (raw payload), so an agent can separate it from siblings 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?

Names specific alternatives and their differentiators: sync_state 'also logs work and returns proceed or pause,' and get_governance_metrics 'returns this read's raw payload.' It also spells out the proof conditions that select the bound vs. unbound path. What's missing is an explicit 'when not to use this' or a direct 'use X instead if...' routing statement, so it stays at 4 rather than 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 declare readOnlyHint=false, openWorldHint=true and non-idempotent, and the description adds context the annotations cannot: no review record is produced, and 'thorough' effort requires cloud privacy plus an operator extension, i.e. a real prerequisite that can block the call. It stops short of stating cost, latency 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?

Two clauses, front-loaded with the action and the key exclusion; nothing is padding. The compression costs some readability – semicolon-separated policy fragments read like notes rather than a sentence – but no information 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 a 12-parameter tool with no output schema, the description covers the pivotal routing and precondition but says nothing about what comes back (response_mode, continuity_token semantics, degraded fallback behavior) beyond what the schema already documents. Adequate, not thorough.

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 earns above baseline by disclosing the cross-parameter constraint (thorough effort needs cloud privacy enabled and an operator extension) that the per-parameter enum descriptions only partially imply.

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

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

States a concrete verb+resource ('Ask a model for advice') and immediately scopes it with 'no review record', which tells the agent this is an advisory, non-governed consultation. It does not name a near-identical sibling beyond request_review, and the phrasing is telegraphic, 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?

Explicitly routes the agent: use this for untracked advice, use request_review when the interaction must be on-record. The alternative and its selection condition are stated, though 'no review record' is compressed enough that the contrast requires a second read.

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

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

Annotations already 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?

Annotations declare non-readOnly, non-destructive, non-idempotent, so the safety bar is lower, yet the description still adds substantial behavioral detail: no-proof calls mint a fresh agent marked caller_proven=false, name-only calls also mint, name= is purely cosmetic and never looks up an agent, and continuity_token across processes 're-opens silent resurrection.' That is unusually candid mutation/resurrection disclosure. It stops short of describing the return shape, hence 4.

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, then the gating behavior, then the client_session_id escape hatch. Every sentence carries a distinct constraint, though the em-dash-heavy phrasing with parentheticals makes it denser than necessary and mildly hard to parse.

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, non-idempotent mutation tool with no output schema, the description covers the minting semantics, the cosmetic-name pitfall, and the cross-process token hazard. It names caller_proven as a returned flag, but does not describe the full return payload, leaving a small gap for a tool with no output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds relationship-level meaning beyond the per-field schema text, explaining name= default behavior, that client_session_id gates read/rename, and that continuity_token is per-process ownership proof rather than a transport claim. It clarifies how the arguments interact, which the flat schema does not.

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 specific verb and resource: resolve the agent bound to the session, or set a cosmetic display name. It immediately qualifies the operation as 'not a plain read,' which distinguishes it from the read-oriented siblings and tells the agent this call can create/persist state.

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

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

It gives explicit selection rules: 'pass client_session_id to read or rename your own session,' and 'for a fresh process call onboard(force_new=true).' The when-to-use guidance is strong, but the recommended alternative 'onboard' does not appear in the sibling list, which weakens the routing advice slightly.

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?

Annotations already mark this as a non-read-only, non-idempotent, open-world mutation, and the description adds real behavioral detail beyond them: the registered-identity precondition, the SESSION_EXISTS refusal, and the wait-state skip behavior. It stops short of describing what a successful review returns or its lifecycle.

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?

Short and front-loaded, leading with the core action before conditions. However, the telegraphic phrasing packs several distinct ideas per sentence and leans on undefined internal jargon, which costs some readability.

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 ten-parameter, destructive-capable, open-world tool with no output schema, the description covers preconditions and a few key parameters but leaves most parameter semantics and the outcome of a review unaddressed. It is viable but not complete given the tool's 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 coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: issue_description acts as the thesis by default, use_brief_as_thesis=false changes call behavior, and reviewed_work_author_agent_ids triggers author recusal. Several of the ten parameters still get no narrative treatment, keeping it short of a 5.

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') and contrasts itself with the consult sibling ('dialectic advances the session; consult is advisory'). The jargon 'governed review' is not self-explanatory, but an agent can identify the action and roughly separate it from alternatives.

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

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

Provides concrete trigger conditions: proxy-filed reviews should pass reviewed_work_author_agent_ids, and it requires a session-owned registered identity. It also gives mode-selection hints (dialectic vs consult) and the use_brief_as_thesis=false path, though it stops short of explicit 'use X instead of Y' exclusions.

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

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

It discloses the non-obvious side effect that each search appends a knowledge_read audit row with a redacted query copy, and explains why readOnlyHint is false even though the operation reads. It also spells out the visibility rules for archived, cold, resolved and closed rows, including the under-3-results fallback, which annotations cannot express.

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 and the sibling pointer come first, then the visibility and audit caveats in three dense sentences with no filler. Every clause carries information an agent would otherwise discover only by trial.

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-output-schema tool it covers the high-risk surprises: audit side effects, unbound-caller support, visibility of archived/cold rows, and where to go for single-record details. The gaps are minor, such as the interaction between limit and the small-result fallback or the default search_mode behavior, which the schema only partially explains.

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 genuine semantics beyond the schema for include_archived, include_cold and status: archived and cold rows surface only when requested or when a query returns fewer than 3 other rows, while resolved and closed always appear. Those filtering knobs are only some of the 25 parameters, so it is not a full 5.

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 shared memory (the knowledge graph)') and immediately names the sibling tool that handles the write path, so an agent can separate this from store_finding without inspecting 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?

It states the trigger ('before you write'), names the alternatives for adjacent actions (store_finding to add, use_tool/update_finding to revise), and adds a call-order rule: it works before start_session unlike the write tools. That is explicit when, when-not, and what-to-use-instead.

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?

Without relying on annotations, the description discloses non-obvious behavior: a bare call is defaulted to force_new or refused under strict identity, a still-live parent claim is rejected as coincidental and cleared, and response_mode='full' retains the raw payload. That is substantially more than the annotations (readOnly=false, idempotent=false) 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?

The primary purpose is front-loaded, but the body is a dense run-on of clauses with unexplained jargon ('digest envelope', 'raw_governance', 'coincidental') and references 'agent_uuid' (an output field, not a param) without setup. Much is information-rich, yet parsing cost is high.

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, no-output-schema identity tool this captures the critical behaviors (identity minting, force_new, succession, response envelope) that an agent needs. It does not address numerous auxiliary params, but the schema documents them fully, so little is genuinely 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 100%, so baseline is 3, and the description adds genuine meaning for key params: it explains what force_new's default fallback does, the succession semantics of parent_agent_id, and the effect of response_mode='full'. Several other params (thread_id, trajectory_signature, process_fingerprint) get no added explanation, keeping this from a 5.

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 states a concrete verb+resource ('Register this process-instance and mint its agent identity') and the two related tools (identity, onboard) are named. However, 'this name adds a digest envelope' and the near-synonymy with onboard make it hard to tell precisely which tool an agent should reach for at bootstrap time.

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

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

It gives real conditional guidance (force_new coercion, parent_agent_id succession rules, 'use identity to inspect or rename'). But the routing sentence 'onboard is the canonical twin; this name adds a digest envelope' is opaque and leaves the agent unsure whether onboard or start_session is the correct entry point.

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 the annotations (readOnly=false, idempotent=false, destructive=false) by disclosing runtime behavior: every call mints a NEW discovery, 'summary' is required at call time despite the schema marking all fields optional, high/critical severity is refused unless the session is bound to a registered agent, low/medium fall back to an anonymous writer id, and there is a budget of 20 findings per hour. These are exactly the non-obvious traits an agent needs before calling.

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 and front-loaded, leading with the write action and the revise alternative. It repeats the search-first/update_finding directive in two places ('search first, to revise one use update_finding' and again in the second paragraph), which is minor redundancy but not bloat.

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 14-parameter write tool with no output schema, the description supplies the missing essentials: the return value (discovery_id), the effective required field, the authorization tiers for severity, the rate budget, and the create-vs-revise-vs-record_result decision. Nothing an agent needs to invoke it correctly is absent.

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-field semantics the schema cannot express: 'summary' is effectively required contrary to the schema's optional marking, the severity-dependent agent-boundary rule, and why 'agent_id' should be left unset. It does not cover all 14 params (e.g. continuity_token, comparison_key), so it stops short of a 5.

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 a durable finding to the knowledge graph') and immediately distinguishes the create path from the revise path (update_finding) and the search path (search_shared_memory). An agent can tell this apart from its siblings 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 routing: use this for a discovery, root cause or correction, use record_result for task/tool/test outcomes, search first, and revise via update_finding. Both the alternative tools and the conditions that select them are named, leaving nothing to inference.

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

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

Annotations 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.