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 covered. The description adds genuinely new context beyond that: there is no recycle bin, deletion is permanent, what the success string looks like, and that an already-absent key yields a not-found error rather than a silent success.

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 sentences, front-loaded with the destructive action and its scope, then the routing guidance, then the return contract. Every clause earns its place; no 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 usefully documents the return contract ('Forgot "KEY"' / not-found error), and for a one-parameter destructive tool the combination of annotations plus the permanent/no-recycle-bin note is fully sufficient.

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% for the single 'key' parameter, so the schema already carries the meaning. The description adds only 'from encrypted agent memory' as scope context, with no key-format or naming-convention guidance. Baseline 3 applies when the schema does the work.

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 ('Permanently delete a single key from encrypted agent memory') and explicitly distinguishes itself from the two most confusable siblings, agent_remember and delete_secret. An agent can route correctly 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 ('retract obsolete or misremembered context') and when-not-to-use, naming both alternatives with the condition that selects each (agent_remember for value updates, delete_secret for real credentials). Nothing is left 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 already declare readOnlyHint, idempotentHint, and non-destructive, so 'Read-only' is redundant. However, with no output schema, the description adds real value by specifying the return shapes ({ ok, data: { key, value } } vs. a key listing with no values), the not-found error path, and the 'Agent memory is empty' state.

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 verb and dual mode, then layers usage and return details efficiently. Dense but every clause carries information; only the redundant 'Read-only' line could be trimmed against the annotations.

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

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

With no output schema, the description fully covers what the tool returns and its error/empty states, and it names the siblings to use for credential or overview needs. An agent has everything required to select and call it correctly.

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 `key` parameter is documented there, so the baseline is 3. The description restates that omitting key lists keys without values, adding little beyond the schema's own wording.

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

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

States a specific verb (read) and resource (encrypted agent memory) and covers both modes: value lookup with a key and key listing without one. It is immediately distinguishable from siblings like agent_remember and agent_forget, and the dual behavior 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 says when to use it ('start of an agent loop to rehydrate prior context', 'look up a single remembered fact') and routes to alternatives ('prefer get_project_context for a redacted overview of secrets and get_secret for actual credential values'). Both the trigger and the exclusions are stated.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=true), and the description adds context beyond them: persistence across MCP sessions, encrypted on-disk storage, that overwriting the same key destroys the prior value, and the exact success return string.

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 usage constraints, then behavioral notes; every clause carries information (persistence, secrecy exclusion, idempotency, return value) with no 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?

A two-parameter, no-output-schema tool whose full behavioral contract — storage location, persistence, mutation semantics, return value, and correct-vs-wrong usage — is stated, leaving nothing an agent needs to call it correctly.

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 both parameters are documented there, including a naming convention. The description adds no syntax or format detail for key/value, 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?

Names a specific verb and resource ('Persist a non-secret key/value note in encrypted, on-disk agent memory') and immediately distinguishes itself from set_secret and the chat scratchpad, so an agent can identify it without opening schemas.

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

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

Gives explicit when-to-use examples ('last rotation date for a key', 'deployment preferences', 'decisions taken in earlier sessions'), an explicit when-not ('do NOT use this to store secrets'), and names the alternative tools (`set_secret`, chat scratchpad) with the condition that selects each.

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: it discloses that autoRotate=false (default) is read-only, that autoRotate=true OVERWRITES expired secret values with generated replacements, and that this may break upstream integrations until propagated. It also flags 'Subject to tool policy' and describes the return payload, adding real behavioral context over the destructiveHint/readOnlyHint flags.

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 sentence is long but front-loads the core action and scoping, then layers alternatives and the destructive caveat. Density is high with little filler, though the single-sentence structure is heavy and could be broken up.

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?

Without an output schema, the description still states what is returned ('a JSON report of per-project findings and any rotations performed'). Combined with the safety, scope, and alternative guidance, an agent has everything needed to call this correctly.

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 meaning beyond the schema: it clarifies that autoRotate's default keeps the call read-only and that enabling it is destructive on the upstream side, reinforcing the schema's own note. projectPaths defaults are already documented in the schema, so the gain is modest.

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 ('multi-project health pass' gathering decay status, audit anomalies, manifest gaps) with an explicit optional mutation mode. It names the sibling tools it is not (health_check, detect_anomalies, check_project) and the scoping difference, so an agent can distinguish it without opening schemas.

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

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

Explicitly frames itself as the canonical 'agent maintenance loop' for a portfolio of repos, then routes the agent to three alternatives with the condition that selects each ('single read-only scope', 'audit-only triage', 'single-project manifest check'). When-to-use and when-to-use-something-else are both covered.

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), but the description adds meaningful context beyond them: the read-only nature plus the specific data window ('most recent ~500 audit events'). It does not mention rate limits or refresh/ordering semantics, so it stops short of 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 purpose, then usage, then return shape. It is dense but each sentence carries weight; the single long final section is slightly packed but not wasteful.

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 analysis tool with 100% schema coverage and no output schema, the description supplies the missing return shape ('{ total, expired, stale, neverAccessed... }'), the data window, and guidance on interpreting results, which is everything an agent needs to select and call it correctly.

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 four parameters are already fully documented in the schema (scope enum, orgId, teamId, projectPath with conditions). The description only alludes to 'secrets in scope' and adds no syntax beyond the schema, so the 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?

The description states a specific verb+resource ('cross-reference the secrets in scope with recent audit events') and the concrete output ('usage profile and rotation/retirement suggestions'). It is clearly distinguishable from siblings like health_check and audit_log.

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 when-to-use ('quarterly hygiene check or input to a planner') plus named alternatives and the conditions that select them ('prefer health_check for decay-only triage and audit_log to inspect access timelines for one key'). Nothing is left 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description nevertheless adds the tamper-evident nature, chronological one-line-per-event format, and the exact empty-result string. It doesn't mention pagination behavior, which is a minor 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 dense sentences with no wasted words; the core definition leads, then usage routing, then behavioral details. Slightly packed but well front-loaded and every sentence earns its place.

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

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

Complete for a read-only filtered-list tool with no output schema: it defines scope, routes to two alternatives, declares read-only, specifies the return line format and the empty-result message. An agent has everything needed to call and interpret it correctly.

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 each parameter already documents omit-for-all semantics, so the schema does the heavy lifting. The description adds only the example 'read' for the action filter, which is marginal value. Baseline 3 is appropriate when the schema is fully documented.

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 (Query) and resource (the q-ring audit log), and immediately characterizes it as 'a tamper-evident record of every read/write/delete touching a secret'. The bracket prefix '[audit]' and the framing make it unmistakably distinct from siblings like export_audit, verify_audit_chain, or detect_anomalies.

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 when-to-use examples ('who accessed KEY recently?', feeding an access timeline) and explicitly routes to alternatives: 'prefer detect_anomalies for automated unusual-pattern detection and health_check for decay-state-plus-anomalies'. Names two siblings and the condition selecting each.

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, so 'Read-only' adds little; the real value is the disclosed return shape `{ allowed, reason?, policySource }` and the documented error 'Missing required parameter for the selected action type'. It could go further on performance or resolution nuances, but it meaningfully extends beyond 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, then usage guidance, then return/error behavior in a logical order. Slightly dense with a few overlapping clauses (the redundant 'Read-only' plus the long error sentence), but every sentence 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?

No output schema exists, yet the description supplies the return shape and the key error case, and the routing to `get_policy_summary` closes the main sibling-selection gap. An agent has everything needed to call this correctly.

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 each parameter and its action-specific requirement is already fully documented in the schema. The description only restates that the matching argument must be supplied for the chosen `action`, adding no new syntax or format detail beyond the schema 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 and resource: ask whether a single intended action would be allowed by the project's `.q-ring.json` policy without performing it. It explicitly distinguishes itself from the sibling `get_policy_summary` by contrasting a single-action dry-run with a whole-policy overview.

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 when-to-use triggers (before calling a potentially-blocked tool, reading a sensitive key, or invoking `exec_with_secrets` with a non-trivial command) and names the alternative (`get_policy_summary`) with the condition that selects it. Nothing is left 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 already declare readOnly/idempotent/non-destructive, and the description reinforces this while adding genuinely new context: it does not mutate the keyring or audit log beyond a 'list' read, and it documents the exact error when no manifest exists. It stops short of describing pagination or the semantics of every returned field, but adds meaningful behavior 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-loaded with the core purpose, then routing guidance, behavior, and return shape in that order. It is dense and effective; slightly long, but each sentence carries distinct information rather than restating the name.

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?

Covers purpose, usage, safety profile, return payload shape (including the meaning of `ready`), and the failure case. With annotations covering read-only safety and the return values described inline in the absence of an output schema, an agent has everything needed to call it correctly.

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 `projectPath` parameter is fully documented in the schema, so the baseline is 3. The description adds no format or default detail beyond what the schema already 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: comparing keys declared in the project's `.q-ring.json` manifest against the actual keyring. It explicitly distinguishes itself from `health_check` (scope-wide decay sweep, no manifest) and `agent_scan` (multi-project scans), so an agent can select it without opening other 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 context ('is this project ready to run' gate before dev server, deploy, or onboarding) and names the two alternatives with the conditions that select them. Nothing is left 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?

Goes well beyond the readOnly/idempotent annotations by disclosing cost scaling ('one outbound request per validatable secret'), audit side effects ('records read audit events'), the exact JSON return shape, and the 'No secrets to validate' empty-scope case. This is rich behavioral context an agent cannot get from the annotations.

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

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

Front-loaded with the core action and scope, then usage, then side effects, then return contract. Every sentence carries distinct information with no 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 four-param, zero-required tool with no output schema, the description supplies the return structure, side-effect cost, audit implications, and empty-result behavior — everything needed to invoke it correctly.

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 schema already documents orgId/scope/teamId/projectPath and their conditional requirements. The description only alludes to 'the requested scope' without adding format or constraint detail, 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 and resource ('Validate every accessible secret ... against its detected provider in a single batch') plus the output artifact. It explicitly differentiates itself from the sibling validate_secret for single-key use.

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 two concrete use cases (CI gate before deploy, pre-rotation health pass) and names the alternative tool with the condition that selects it ('prefer validate_secret for a single key'). No inference required.

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/readOnlyHint/idempotent, but the description adds substantial value beyond them: no undo and no built-in trash, all env states removed, an audit-log 'delete' event is written, matching hooks fire, and it is subject to tool policy. This is exactly the behavioral context a mutation tool 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 destructive action and constraint, then routing, then side effects, then return values. Dense but every sentence earns its place; slightly long, keeping it just below 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?

No output schema exists, yet the description supplies the return contract ('Deleted "KEY"' or a not-found error), the side effects (audit event, hooks), and the irreversibility caveat. Complete for a 5-parameter destructive 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 every parameter (key, scope, orgId, teamId, projectPath) is already documented in the schema. The description reinforces scope-based behavior ('for the given scope', not-found 'in the requested scope') but adds no syntax or format detail beyond the schema, so the 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 ('Permanently remove a secret value ... from the keyring for the given scope'), scopes it, and explicitly distinguishes itself from three siblings by naming conditions under which each alternative is preferred. An agent can select this over disentangle_secrets/remove_hook/tunnel_destroy 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 both when-to-use ('credential is being retired or was created in error') and when-not-to-use with named alternatives and their selecting conditions (disentangle_secrets for breaking sync links without erasing, remove_hook for callbacks, tunnel_destroy for ephemeral tunnels). Nothing is left 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 already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is largely covered; the description still reinforces 'Read-only; never mutates secrets or the audit log' and discloses the output shape ('one line per finding formatted [type] description', or a clean-log message). It could say more about scan cost or log-window limits, but it goes well 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?

Three dense sentences with the '[audit]' tag and the core action front-loaded, followed by routing guidance and the return contract. Slightly packed but every clause earns its place; no 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 compensates by specifying the return format and the empty-case message, and it covers routing and safety. An agent has everything needed to call and interpret this tool correctly.

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% and the single 'key' parameter is fully documented in the schema (narrow-to-key vs scan-all), so the description adds no syntax or format detail beyond it. Baseline 3 is correct 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?

States a specific verb and resource ('Scan the audit history') and enumerates the concrete patterns detected ('burst reads of the same key, off-hours access'). It also explicitly distinguishes itself from siblings health_check and agent_scan, so an agent can route correctly 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 ('quick triage signal when investigating a single key or before letting an agent rotate credentials') and names two alternatives with the conditions that select them (health_check for scope-wide decay+anomaly summary, agent_scan for multi-project JSON with auto-rotation). No inference required.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds specific detection sources in priority order (QRING_ENV, NODE_ENV, .q-ring.json, git branch) and the return format, which are valuable behavioral details beyond 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?

The description is front-loaded with the core purpose, then usage guidance, detection logic, and return format. Each sentence contributes necessary information without redundancy.

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?

Given the tool's detection complexity and the absence of an output schema, the description fully explains the resolution process, priority order, and return values. No critical information is missing for an agent to invoke it correctly.

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 fully documents the single optional projectPath parameter. The description adds no additional parameter meaning, 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 'Resolve' and resource 'environment slug', and clarifies it detects the env the invocation should collapse to. It distinguishes itself from sibling tools like get_secret and env_generate by suggesting when to prefer those instead.

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 says to use before reading secrets to mirror the auto-picked env, and to prefer passing explicit env to get_secret/env_generate when known. This gives clear when-to-use and when-to-use-alternative 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 declare non-read-only, idempotent, non-destructive, but the description goes beyond them by specifying that only metadata mutates and values stay untouched, that running on an unlinked pair succeeds with no effect, and that the operation is subject to tool policy. It even names the exact return string.

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

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

Four short sentences, front-loaded with the core action, then eligibility, alternatives, mutation scope, and idempotency. No filler; each sentence carries distinct 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 metadata-only mutation with no output schema, the description covers when to use it, what changes, what does not change, idempotency, and the return value, leaving no practical gap for an agent to call it correctly.

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 sourceKey/targetKey and the scope/path parameters are already documented. The description adds no additional parameter semantics (e.g., whether sourceKey and targetKey may be swapped), so the 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 precise verb+resource ('Break the sync link between two previously entangled keys') plus the downstream consequence ('future rotations no longer propagate'), which distinguishes it from entangle_secrets and delete_secret without needing 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 explicit when-to-use triggers (retiring a key, intentional divergence) and names the two alternatives that select different behaviors: delete_secret for erasing values and entangle_secrets for recreating the link. Nothing is left 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 already declare idempotentHint, destructiveHint=false, and readOnlyHint=false, but the description adds meaningful non-structured context: it mutates only envelope metadata (values untouched), is subject to tool policy, and returns a specific confirmation string. The idempotency claim duplicates the annotation rather than extending it, keeping this just below a top score.

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 core action and routing guidance are front-loaded, and most sentences earn their place. Slightly dense with multiple parenthetical asides, but nothing is wasteful.

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?

Despite no output schema, the description states the return value explicitly, covers mutation scope, idempotency, and the sibling-based reversal path. An agent has everything needed to invoke it correctly.

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 six parameters are already documented in the schema, including scope semantics and projectPath defaults. The description adds no new parameter-level detail, so the 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 and resource ('Link two keys') and clarifies scope ('across the same or different scopes') plus the propagation semantics. An agent can immediately distinguish this from set_secret and disentangle_secrets, which are named directly.

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 states when to use it (one logical credential under multiple names that should never drift), names the preferred alternative for unrelated values (set_secret), and points to the reverse operation (disentangle_secrets) with the note that it does not delete values.

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 cover read-only, idempotent, non-destructive, closed-world. The description adds substantial behavioral detail beyond that: it records 'read' audit events, collapses superposition for the requested env, describes return value format (raw `.env` text), and details warning/placeholder behavior for MISSING/EXPIRED/STALE keys so the file remains valid.

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 sentences, front-loaded with the core operation, then usage guidance with alternatives, then behavioral details. Every sentence earns its place with no redundancy.

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?

Complete for a tool with no output schema and full schema coverage: it explains purpose, usage, audit behavior, env-collapse semantics, and exactly what the returned text contains including warning markers and placeholder formats.

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 well-documented by the schema itself. The description mentions the env and project concepts in narrative context but adds no syntax or format beyond what the schema provides. 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?

Specific verb and resource: 'Render a complete `.env` file body from the project's `.q-ring.json` manifest, resolving each declared key from the keyring.' It clearly distinguishes itself from siblings export_secrets and exec_with_secrets by naming them and their differing behavior.

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 when-to-use ('when a build step or local runtime needs a real `.env` materialized on disk') and when-to-prefer-alternatives ('prefer `export_secrets` when you want every key in scope... and `exec_with_secrets` to inject secrets into a child process without writing them to a file').

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 mark it destructive/openWorld, but the description adds the crucial context that is not in structured fields: it spawns a real child process with the command's own side effects, it is subject to BOTH tool policy and exec policy (allowlist/denylist), and both output streams are scrubbed against injected values. That is exactly the behavioral detail an agent needs before invoking a destructive executor.

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 verb and both key behaviors, and every sentence carries a distinct fact (use cases, alternatives, side effects, policy, return format). It is on the long side with some dense clauses, but no sentence is 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?

No output schema exists, and the description compensates by specifying the return format (`Exit code: N`, then `STDOUT:`/`STDERR:` blocks) and stating the scrubbing applies to both streams. Side effects, policy gating, and secret scope are all covered, so nothing an agent needs to invoke 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 description coverage is 100%, so the schema already documents all nine parameters including the security-relevant `profile` semantics. The description adds redaction and policy context but does not extend param meaning beyond the schema, 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 (run) and resource (child shell command) plus the two defining mechanisms: secret injection as env vars and redaction of leaked values from stdout/stderr. It explicitly distinguishes itself from siblings env_generate and validate_secret, so an agent can route 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 concrete use scenarios (`npm run db:migrate`, `terraform plan`, `vercel deploy`) and a when-not: use `env_generate` to write a .env to disk and `validate_secret` for liveness checks. Both alternatives and their selecting conditions are named explicitly.

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/idempotent/destructive=false, so 'Read-only' adds little; however, the description adds real context: output is returned as rendered text with no JSON wrapper, and time filters are applied to event timestamps before formatting. Those behavior nuances are not expressible in 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?

Well front-loaded: the core action and artifact lead, followed by routing guidance, safety, return shape, and format semantics. Slightly dense and mildly overlaps the enum descriptions in the schema, 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?

There is no output schema, but the description compensates by describing the return (rendered text, no JSON wrapper) and format-specific rendering. Combined with annotations covering safety, an agent has everything needed to invoke it correctly.

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 by spelling out the concrete shape of each format ('jsonl' one event per line, 'json' a single array, 'csv' a header row plus events) and clarifying filter-then-format ordering, which the schema does not state.

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 (export the audit log) and the artifact type (portable text, no JSON wrapper). It explicitly names the sibling alternatives `audit_log` and `verify_audit_chain`, so an agent can differentiate 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?

Explicitly enumerates when to use it (compliance exports, after-the-fact investigations, handing off to a non-MCP consumer) and when to prefer alternatives (`audit_log` for an in-conversation tail, `verify_audit_chain` to confirm integrity first). This is a textbook when/when-not/alternative 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?

Adds substantial behavior beyond the annotations: it reads values and collapses per-env superposition, writes one 'export' audit event per included secret, returns raw text with no JSON wrapper, errors when no secrets match, and surfaces plaintext values. Annotations only cover the safety profile; the description supplies the audit-write side effect, output shape, and error condition.

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, then alternatives, then behavioral traits and caveats. Though multi-sentence, every sentence carries distinct information (alternatives, audit side effects, return shape, error case, plaintext warning) with no redundancy.

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 the return value ('returns the rendered text directly, no JSON wrapper') as well as the failure mode. Combined with the alternative routing and behavioral disclosure, an agent has everything needed to call and interpret it.

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 all eight parameters are documented there, so the schema does the heavy lifting. The description reinforces superposition collapsing for `env` and format behavior, but adds little syntax or format detail beyond what the schema already provides. 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 ('Render multiple secrets as a single .env or JSON document') and clarifies the goal ('for piping into another tool or file'). It explicitly distinguishes itself from env_generate and teleport_pack, so an agent can route 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?

Names the use case ('one-off export or copy') and then gives explicit alternatives with the conditions that select them: env_generate when output is driven by the .q-ring.json manifest, teleport_pack for an encrypted shareable bundle. This is exactly the when/when-not/alternatives guidance the dimension asks for.

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 and destructiveHint=true; the description adds value beyond them by clarifying that the call is read-only without `saveAs`, mutates with one 'write' event when `saveAs` is set, and describing both return shapes. It does not state whether `saveAs` overwrites an existing keyring entry, which is a relevant destructive-behavior 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?

Front-loaded with purpose, then usage guidance, then behavioral detail. It is fairly long but every sentence carries information; minor redundancy between the intro's 'optionally store' and the later `saveAs` explanation.

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?

Despite no output schema, the description documents both return modes (a summary string with `saveAs`, JSON `{ ok, data: { value } }` without). With zero required parameters, 100% schema coverage, and clear mutation semantics, an agent has everything needed to call it correctly.

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 fully documents all 8 parameters including formats, scopes, and defaults. The description reinforces `saveAs` semantics but adds little syntax or meaning beyond what the schema provides; 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 (generate) and resource (cryptographically random secret), names the mechanism (Node's CSPRNG), and clarifies the optional store step. It also actively distinguishes itself from `rotate_secret` and `set_secret`, so an agent can pick correctly without opening sibling 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?

Explicitly states when to use this tool ('credentials that you control'), when to prefer `rotate_secret` (issuer-issued credentials), and when to prefer `set_secret` (values already in hand). Alternatives and their selecting conditions are named outright.

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, and destructiveHint=false, so safety is covered. The description adds behavior beyond that: pretty-printed JSON output and, notably, that a missing policy file returns an empty/default summary rather than an error so callers can branch on counts — a non-obvious error-handling contract that usefully informs invocation.

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, followed by usage/alternative routing and then behavioral notes. Every sentence carries distinct, non-redundant information with no padding.

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?

Despite having no output schema, the description explains the return shape (pretty-printed JSON with allow/deny counts) and the missing-file fallback, which is exactly the return-value context an agent needs. Nothing required to call 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 100% for the single `projectPath` parameter, and the schema already documents the absolute-path semantics and the CWD default. The description adds no further parameter-level detail, 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 and resource ('Return a high-level summary of the project's `.q-ring.json` governance policy') and enumerates the contents (allow/deny rule counts for tools, key reads, exec commands, approval/rotation requirements). It also names the sibling it is not ('prefer `check_policy` for a precise per-action verdict'), so an agent can distinguish it without opening schemas.

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

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

Explicitly states when to use it ('to orient an agent... before attempting policy-restricted actions') and when to prefer the alternative ('prefer `check_policy` for a precise per-action verdict'). The routing condition between summary vs. per-action verdict is fully 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 already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explicitly states no plaintext secret values are ever returned, the return is pretty-printed JSON, and the shape is intentionally broad and may grow, advising defensive reading. It doesn't cover access/auth requirements or rate limits, keeping it short of 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?

The description is front-loaded with the core purpose, then usage, then safety, then return shape. It is dense but each sentence carries distinct information. It runs slightly long with the enumeration of snapshot contents, 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 read-only, no-output-schema, zero-required-param aggregate tool, the description covers purpose, usage routing, exclusions, safety guarantees, and return-shape expectations. An agent has everything needed to call it correctly and interpret the response defensively.

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 schema already documents every parameter with examples, enums, and scope-dependency rules. The description adds no parameter-level detail, so baseline would be 3; it earns a 4 only because it establishes the session-orientation frame and value-safety scope that give the parameters their intended context.

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 opens with a specific verb-resource pair ('Return a single redacted snapshot') and enumerates the exact contents (secrets present, detected env, manifest declarations, providers, hooks, audit activity). It explicitly distinguishes itself from siblings list_secrets, check_project, and audit_log, so an agent can route correctly 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?

It states the precise usage condition ('Use this as the very first call in a session to orient the agent') and gives three named alternatives with the condition that selects each. There is no ambiguity about when this tool is preferred over the alternatives.

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 by disclosing that it collapses superposition, writes a 'read' audit event, is subject to policy that may return 'Policy Denied', and returns a specific JSON shape. These are non-obvious behavioral traits the annotations (readOnly/idempotent/non-destructive) do not 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?

Front-loaded with the core purpose followed by alternatives and side effects; every sentence earns its place. It is dense but not padded, though slightly long for a read 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?

Despite no output schema, the description supplies the return contract ('Returns JSON { ok, data: { key, value } }') and error behavior, plus policy and audit side effects. 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?

Schema description coverage is 100%, so all six parameters are already well documented in the schema. The description adds only the general notion of per-env superposition, which the env schema field already explains. Baseline 3 is appropriate when the schema carries the load.

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 the plaintext value of a single secret') and immediately distinguishes itself from siblings by naming inspect_secret, has_secret, and exec_with_secrets. An agent knows exactly what this tool returns 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?

Explicitly states the trigger condition ('when an agent needs the actual credential to call an external API or inject into a runtime') and routes to the right alternative for each other need (metadata, presence check, indirect execution). This is textbook when/when-not guidance.

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

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

Adds traits annotations cannot convey: it does not record a 'read' in the audit log, and it is decay-aware, returning 'false' for expired secrets while the value remains in the store. These are non-obvious behaviors that materially affect how an agent interprets the result.

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, then layers usage, alternative routing, and behavioral caveats in tight sentences. Every sentence earns its place with no redundancy.

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 compensates by specifying the return format ('the literal text true or false') and the decay caveat. For a boolean existence check, nothing an agent needs to call or interpret it 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 description coverage is 100%, so the schema already documents key, scope, orgId, teamId, and projectPath in detail. The description only references 'the requested scope' and adds no syntax or format meaning beyond the schema, so the 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 ('Check whether a secret exists') with an explicit scope qualifier ('in the requested scope without reading the value'). This distinguishes it clearly from get_secret and inspect_secret, so an agent can select it 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 an explicit when-to-use ('cheap precondition before reading or writing... to skip prompting the user for a key that is already configured') and names the alternative with its selecting condition ('Prefer inspect_secret when you also need metadata'). Both the use case and the sibling routing 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description reinforces it with 'Read-only — never writes' and, more valuably, discloses the return shape in detail since no output schema exists. It doesn't add permission/auth or rate-limit context, so it stops short of 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?

The purpose is front-loaded, followed by alternatives and then return behavior, with no wasted sentences. The return-format enumeration is the longest part but earns its place because no output schema exists; it is slightly dense but well ordered.

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?

Given four optional params, a 100%-covered schema, and no output schema, the description supplies exactly the missing piece: the structure of the multi-line text summary (header counts, EXPIRED/STALE lines, anomaly lines). An agent has everything needed to call and interpret it.

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 schema itself documents orgId, teamId, projectPath, and the scope enum with defaults and required-when conditions. The description adds no parameter-level detail, so this is the baseline 3 where structured fields do 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 states a specific verb and resource ('Run a single read-only sweep over every secret') plus the exact output content (healthy/stale/expired counts and audit anomalies). It actively distinguishes itself from siblings by naming check_project, detect_anomalies, and agent_scan and the conditions that separate them.

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 explicitly positions the tool as the default 'is everything OK?' command, then routes agents to alternatives with reasons: check_project for manifest compliance, detect_anomalies for audit-only triage, agent_scan for multi-project JSON or auto-rotation. This is exactly the when/when-not/alternatives coverage the dimension rewards.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds substantial beyond-schema context: one write per parsed key, a 'write' audit event per key, skipExisting/overwrite semantics, and dryRun producing the same summary with no writes. It also discloses the parsing features supported (comments, quotes, \n escapes). Nothing contradicts 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?

Dense but organized: purpose first, then routing, then mutation/audit behavior, then parsing and return semantics. Every clause carries information, though the run-on middle sentence could be split for faster scanning.

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 still documents the return value (multiline summary of imported and skipped keys) and dryRun's parallel output. For a 5-param batch-import tool, an agent has everything needed to call it correctly.

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 meaning beyond it by explaining the observable effect of skipExisting (keys land in the 'skipped' list rather than overwritten) and dryRun (no writes, same summary). Scope/format details still rest on 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+resource ('Parse dotenv-formatted text and store each key/value pair into the keyring') and explicitly names the sibling alternatives set_secret and teleport_unpack. An agent can distinguish it from other import/write 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 the two concrete trigger scenarios (migrating a .env file, onboarding a project) and routes the agent: prefer set_secret for a single key, teleport_unpack for encrypted bundles. Explicit when/when-not/alternatives 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds non-obvious behavior: it never exposes the value and does not write a 'read' event for that reason, plus an explicit not-found error case. This is meaningful context beyond the annotations, though auth/permission requirements are not stated.

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 purpose, then alternatives, then behavior, then return shape. The field enumeration is long but earns its place since no output schema exists; a single sentence of it is arguably expendable.

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 compensates by enumerating the returned fields (key, scope, type, decay, entangled, etc.), and it covers alternatives, side effects, and error behavior. An agent has everything needed to call and interpret it.

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 each parameter (key, orgId, scope, teamId, projectPath) is fully documented in the schema, including scope-conditional requirements. The description adds no parameter-level syntax or format detail, so the 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 ('Show full metadata for a single secret') and immediately scopes it by what it does NOT do ('without ever revealing the value'). It explicitly names and differentiates from siblings get_secret, list_secrets, and audit_log, so an agent can route correctly 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 conditions ('to understand the shape of a key before reading it or to debug why is this expired/stale') and names the three alternatives with the condition that selects each. Nothing is left 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 destructiveHint=true and readOnlyHint=false, but the description adds materially: fix:false is read-only, fix:true mutates listed source files in place, writes one new secret per finding to the keyring, advises reviewing with git diff, and discloses the return shape. This is rich behavioral context beyond the structured fields.

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 primary action, then routes to alternatives, then covers the mutation/read-only split and the return value. Dense but every sentence carries information relevant to calling it correctly.

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?

Covers action, alternatives, the risky fix flag semantics, and the return format (with the empty-result string). For a destructive, six-parameter tool with no output schema, nothing an agent needs 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 description coverage is 100%, so all six parameters are already documented in the schema. The description reinforces the fix flag's dual behavior but adds no syntax or format detail beyond what the schema fields already provide, so the 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 (Inspect/scan) and resource (a specific list of files) plus the conditional mutation behavior. It also explicitly distinguishes itself from scan_codebase_for_secrets and import_dotenv, so the agent can tell them apart 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 ('migrate a known set of files, e.g. just-changed files in a pre-commit hook') and names two alternatives with the conditions that select them (whole-tree audit vs. .env ingestion). Nothing is left 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 already declare readOnlyHint and idempotentHint, so the safety profile is covered; the description's 'Read-only' is largely redundant. It does add value by disclosing the return shape (pretty-printed JSON array) and the empty-registry sentinel string, which annotations do not 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?

Three tight sentences: purpose first, then usage routing, then return format. No filler, and the routing guidance is front-loaded rather than 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?

With no output schema and no parameters, the description carries the return-value burden and does so, covering both the populated array and the empty case. Nothing an agent needs to call this 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema shows. Baseline 4 applies since no parameter semantics are needed.

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 ('Enumerate every registered lifecycle hook') and enumerates the returned fields (match criteria, delivery type, enabled flag, description). It is clearly distinguishable from siblings like register_hook and remove_hook.

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 three concrete use cases (find a hook id before remove_hook, audit wired-up side effects, diagnose a hook that did not fire) and explicitly names the dependent sibling tool. Both when-to-use and the alternative are covered.

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 the description reinforces 'Read-only.' More valuably, it discloses the return shape (JSON array of {name, description, prefixes}) and explains that `prefixes` are literal key prefixes used for auto-detection – behavioral context beyond the annotations.

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

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

Front-loads the purpose, then usage, then read-only note, then return shape – in that priority order. Every sentence carries distinct information; nothing is redundant with structured fields.

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 burden of describing the return payload, which it does fully ({name, description, prefixes} and what prefixes mean). Nothing an agent needs to call or interpret this tool 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?

The tool takes no parameters, so the baseline is 4. The description nonetheless explains the semantics of the returned `prefixes` field (e.g. 'sk-' for OpenAI), which is the closest analogue to parameter meaning for a zero-arg discovery tool.

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 ('Enumerate') and resource ('secret-validation providers q-ring knows how to call') with concrete examples (OpenAI, Stripe, GitHub). It also names the sibling tools (validate_secret/rotate_secret) that consume the output, so an agent can distinguish it from the many other list_* tools.

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

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

Explicitly states two use cases: discovering the `provider` string to pass to validate_secret/rotate_secret, and checking whether a custom provider is registered. This routes the agent correctly relative to siblings without requiring 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 already cover readOnly, idempotent, non-destructive, and closed-world. The description adds the crucial non-obvious constraint that values are NEVER returned, plus a full return-shape contract, which is real added context despite no output schema.

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?

Information-dense and front-loaded with the verb/resource and the value caveat, but the return-shape sentence is long. Nothing is wasted; 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?

Given 8 params (all optional) with full schema coverage, read-only annotations, and no output schema, the description supplies the missing return contract and value-safety guarantee, leaving no gap for an agent to call it incorrectly.

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 each parameter is richly documented in the schema; the description adds no parameter-specific guidance. Baseline 3 is appropriate when the schema carries the full burden.

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 (list) and resource (secret keys and quantum metadata) with clear scope, and explicitly distinguishes itself from siblings by naming inspect_secret, analyze_secrets, and health_check with their distinct purposes.

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 states when to use it ('discover what secrets exist before reading or writing') and routes to the correct alternatives for different needs, 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?

Goes well beyond annotations by disclosing the on-disk registry mutation, the hard precondition that at least one of key/keyPattern/tag is required or the call errors, and the return contract (JSON entry including an assigned `id` to be used with `remove_hook`). These are behaviors the readOnlyHint/idempotentHint flags alone do not 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?

Front-loaded with purpose in the first clause, then usage, side effects, preconditions, and return shape — dense but no filler. Every sentence adds a distinct fact an invoking agent needs.

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

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

For an 11-parameter mutation tool with no output schema, the description covers side effects, precondition errors, return payload contents, hook environment variables ($QRING_HOOK_KEY/$QRING_HOOK_ACTION), and the follow-up tool (remove_hook). Annotations and schema fill the remaining type/enum details.

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, but the description adds a cross-parameter constraint absent from the schema: at least one match criterion (key, keyPattern, or tag) is required or the call fails. It also notes the returned `id`'s purpose with `remove_hook`. Individual parameter meanings remain schema-only, so not 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?

Specific verb+resource: 'Register a side-effect (shell command, HTTP webhook, or process signal) that fires automatically when a matching secret is written, deleted, or rotated.' It explicitly distinguishes itself from siblings by naming agent_remember (fact storage) and agent_scan (scheduled rotation) as the wrong tools for those jobs.

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 when-to-use scenarios ('restart a service after rotation, post to Slack on delete, kick a build'), explicit alternatives ('prefer agent_remember for storing facts'), and an exclusion ('not the right tool for time-based scheduled rotation — use agent_scan'). This is exactly the when/when-not/alternative triad.

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, readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: it enumerates untouched surfaces (secret values, audit log, env states) and nuances the idempotency hint by clarifying an already-absent id returns not-found rather than partial work, plus states the success return string.

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 effect, then alternatives, then scope guarantees. Every sentence carries information, though the 'idempotent in spirit' clause is slightly wordy.

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-param mutation with no output schema, the description covers the action, the blast radius, the alternative tools, idempotency behavior, and the success return value. An agent has everything needed to call it correctly and safely.

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 param already documents its origin (register_hook / list_hooks, opaque string). The description's 'registry id' phrasing reinforces but does not extend that meaning, so the schema is doing 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?

States a specific verb and resource ('Detach a single lifecycle hook by its registry id') plus the effect ('so it stops firing'). It explicitly distinguishes itself from nearby siblings delete_secret and tunnel_destroy, so an agent can route correctly without opening schemas.

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

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

Gives an explicit use case ('retire a specific webhook/command without touching any secrets') and names two alternatives with the conditions that select them. Nothing is left to inference about when this tool is the right 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?

Goes well beyond the annotations: discloses the 'write' audit event, outbound provider network calls, the return shape `{ rotated, newValue?, message?, ... }`, and the failure semantics (rotated=false leaves existing value untouched). The annotations cover the safety profile, and the description layers concrete operational detail on top.

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 action, then when-to-use, then behavioral side effects and return contract in tightly packed sentences. Every clause carries distinct information; 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?

Although there is no output schema, the description documents the return fields and the failure state, and it covers mutation effects and network behavior for a destructive operation. An agent has everything needed to call this correctly.

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 six parameters (key, orgId, scope, teamId, provider, projectPath) are already documented with examples and scope conditions. The description adds no syntax or format detail beyond the schema, so 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+resource: 'Ask the upstream provider to issue a fresh credential for this secret and store the new value back into the keyring.' It distinguishes itself from `generate_secret` (self-managed values) and `agent_scan --autoRotate` (sweep rotation), so an agent can route correctly 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?

Explicit trigger conditions ('expiring, leaked, or part of a scheduled rotation') plus two named alternatives with the conditions that select them. Nothing is left 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 real context beyond the annotations: it honors `.gitignore`, never modifies source files, returns a defined JSON finding shape, and warns that false positives are possible and require review. The safety profile (read-only) is already covered by the annotations, so the description's additional value is the gitignore behavior and the false-positive caveat.

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 every sentence earns its place: scope, technique, routing to the alternative, read-only guarantee, gitignore behavior, return shape, and the false-positive caveat. Front-loads what the tool does before the caveats, with no 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?

No output schema exists, and the description compensates by describing the JSON finding fields and the clean-result string. Combined with the routing guidance and caveats, an agent has everything needed to invoke and interpret this tool correctly.

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 `dirPath` parameter, so the schema already documents its semantics and recursion. The description only restates 'walk a directory tree' without adding format or edge-case guidance, so the baseline of 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 ('scan' a directory tree for hardcoded secrets') plus the technique used (regex heuristics plus Shannon-entropy scoring). It also distinguishes itself from the sibling `lint_files`, so an agent can tell the two apart without opening either schema.

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

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

Explicitly frames the tool as a one-shot 'is anything leaking in this repo?' audit before commit/release and names the alternative (`lint_files`) with the exact condition that should route the agent there (known specific files, optional auto-fix). When-to-use and when-to-prefer-alternatives are both present.

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 destructiveHint=true, idempotentHint=true, readOnlyHint=false, openWorldHint=false. The description adds rich context beyond these: it specifies that it 'Mutates the keyring (overwrites any existing value at the same key/scope)' confirming the destructive nature, writes a 'write' event to the audit log, triggers any matching hooks, is subject to tool policy, and even describes the return value format. This exceeds the annotation burden.

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 description is dense but well-structured: first sentence states purpose and features, second gives usage alternatives, third describes side effects, fourth notes policy, fifth specifies return format. Every sentence earns its place, and 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?

Given 12 parameters with 100% schema coverage, no output schema, and annotations covering safety hints, the description is complete. It covers purpose, usage alternatives, side effects, policy, and return format. An agent has everything needed to call this tool correctly.

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 meaning by explaining how env interacts with default slot ('per-env superposition'), mentions TTL/decay, description, tags, and rotation hints without repeating schema details. However, it does not add syntax or format details beyond what the schema already provides, 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?

States a specific verb+resource ('Create or overwrite a single secret value') and explicitly enumerates the features (TTL/decay, per-env superposition, description, tags, rotation hints). It clearly distinguishes itself from siblings by naming import_dotenv, generate_secret, and entangle_secrets as alternatives for different use cases.

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 explicit when-to-use ('Use to add or update one key at a time') and when-not alternatives with conditions ('prefer import_dotenv for bulk .env ingest, generate_secret (with saveAs) to generate-and-store in one step, and entangle_secrets instead of duplicating'). This is comprehensive 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?

Goes well beyond the annotations by disclosing the side effect of binding an HTTP server, the process-wide singleton behavior (re-running returns the existing URL rather than starting a second server), that secret values are never exposed, and that the return value is a URL string. Annotations are absent from the description's remit here except for safety hints, and this text adds substantial operational context.

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 action and resource, then layers usage routing, side effects, and return value in four dense sentences with no filler. Every sentence earns its place.

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

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

Despite having no output schema, the description names the return value (URL string), the singleton constraint, the binding side effect, and the secret-safety guarantee. An agent has everything needed to call it correctly and set expectations.

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 port parameter is already fully documented in the schema (default, failure mode). The description only echoes 'on the requested port' without adding format or constraint meaning. Baseline 3 is appropriate when the schema carries the parameter semantics.

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 ('Start a local web dashboard') plus exactly what it streams (KPIs, secret tables, manifest gaps, hooks, audit events, anomalies via SSE). It explicitly names the siblings it is not, so an agent can distinguish it from health_check/analyze_secrets 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?

Gives an explicit when-to-use condition ('wants a richer visual surface than chat output') and names the alternatives ('prefer health_check / analyze_secrets for one-shot text summaries'). The routing decision is fully determined.

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 behavior. The description adds important traits beyond annotations: AES-256-GCM encryption, base64 ciphertext output, audit-event recording, passphrase dependence for unpacking, direct bundle return, and the specific error when no secrets match.

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 operation, then offers alternatives, then covers mechanism, return value, and error behavior. It is dense but every sentence earns its place and there is no 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 complex crypto handoff tool with no output schema, the description supplies the return type, passphrase requirement, audit side effect, error case, and sibling alternatives. The schema handles parameter details, so an agent has enough context to invoke it correctly.

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 input schema already documents keys, scope, orgId, teamId, projectPath, and passphrase. The description reinforces that the passphrase must match teleport_unpack, but adds little parameter syntax beyond the schema, 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 and resource: encrypt/pack secrets into a single AES-256-GCM bundle. It explicitly distinguishes itself from export_secrets and tunnel_create, so an agent can route correctly without opening sibling 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: hand off a curated set of credentials to another developer or environment. It names the preferred alternatives export_secrets for plaintext .env output and tunnel_create for ephemeral same-machine delivery, and points to teleport_unpack as the reverse operation.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and the description adds real value beyond them: each imported secret emits a 'write' event, scope is honored, and bad passphrase/tampering yields JSON {ok:false} with isError:true. It does not address whether existing keys at the target scope are overwritten, which is the main destructive risk an agent would want spelled out.

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 the sibling reference, and each later sentence carries condition/return/error information rather than filler. It is somewhat dense and runs long for a single paragraph, but no sentence 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?

With no output schema, the description fully covers the return contract (success string, dryRun listing format, JSON error shape) and the mutation/scope behavior. For a 7-parameter mutation tool with only two required inputs, an agent has everything needed to invoke it correctly.

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 seven parameters (including scope enum, dryRun default, and teamId/orgId/projectPath requirements) are already documented in the schema. The description reinforces dryRun's preview purpose and the scope concept but adds no syntax or format detail beyond what the schema provides, 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 ('Decrypt... and import') plus resource ('bundle produced by teleport_pack', 'local keyring'), and explicitly ties itself to its sibling teleport_pack. An agent can distinguish it from import_dotenv or set_secret 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 clear when-to-use context ('on the receiving machine after a packer hands you the bundle and passphrase out-of-band') and a recommended precondition (prefer dryRun=true first). It does not, however, name alternative import paths (e.g., import_dotenv, set_secret) or state when this tool should not be chosen.

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), and the description adds genuinely non-obvious traits: values stay in process memory, never touch disk, are lost on restart, and creation is subject to tool policy. It also names the downstream tools (`tunnel_read`/`tunnel_destroy`) that consume the returned id.

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 purpose and scope, then usage, behavior, and return shape in a tight sequence with no filler. It is a single dense block rather than cleanly separated sentences/lines, which slightly hurts scannability for a six-part message.

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, and the description compensates by specifying the return shape (`{ ok, data: { id } }`) and the opaque-id contract for `tunnel_read`/`tunnel_destroy`. Combined with the in-memory-loss caveat and policy note, an agent has everything needed to call and follow up correctly.

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 `value`, `maxReads`, and `ttlSeconds` including their self-destruct semantics. The description adds only indirect guidance (mentioning `ttlSeconds` in the `set_secret` comparison and warning that omitting a TTL makes `maxReads` strongly advisable), which is useful but not deep parameter elaboration.

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 ('stash a one-shot or short-lived secret in the q-ring server's process memory') plus the concrete artifact returned ('an ID that can be used to read it back'). It explicitly contrasts itself with the sibling `set_secret`, so an agent can pick between them 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 concrete use cases (npm OTP codes, magic-link tokens, copy/paste relay) and an explicit routing rule: prefer `set_secret` with `ttlSeconds` when a tracked, auditable secret is wanted. This is a clear when-to-use and when-to-use-something-else 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?

Goes well beyond the destructive/idempotent annotations by disclosing what is destroyed (in-memory only, not persisted), that it bypasses reads and TTL, and the exact success ('Destroyed ID') and failure (not-found) 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?

Four tight sentences, front-loaded with the action and scope, then when/when-not, then side effects, then return values. No 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 still supplies the return contract and error behavior, and the mutation scope is clear despite rich annotations. Nothing needed to call 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 description coverage is 100% for the single `id` parameter, so the schema already carries the contract. The description only adds the state semantics of an unknown/already-gone ID, which is a minor increment over 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 and resource ('Immediately remove a tunnel from memory') with scope qualifiers ('regardless of remaining reads or TTL'), which cleanly separates it from tunnel_read, tunnel_list, and tunnel_create.

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 names the trigger case (cancelling before delivery, wrong recipient, rotated secret) and the negative case (prefer letting `maxReads`/TTL handle normal cleanup). The alternative-to-this-tool decision is fully 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, lowering the bar. The description nonetheless adds non-obvious behavior: secret values are never included in the output, and it specifies the exact return line format and the empty-list literal.

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 purpose and usage before the format details; every sentence carries information. The standalone 'Read-only.' sentence duplicates the readOnlyHint annotation, a minor redundancy that keeps it out of the top band.

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 correctly supplies the return shape and the empty-case behavior. For a zero-parameter, read-only listing tool this covers everything an agent needs to call and parse it.

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?

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter syntax left for the description to compensate for.

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 (enumerate active tunnels in the q-ring server) plus the exact payload returned (remaining read budget and TTL). It is clearly distinguishable from siblings tunnel_create, tunnel_read, and tunnel_destroy by naming its enumeration/audit role.

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 two concrete use cases: auditing what is still in memory and recovering a forgotten tunnel ID. It does not explicitly name an alternative tool or state when not to use it, so it falls short of the top band.

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: it discloses self-deletion-by-design, read-counter increment, auto-destroy when maxReads is set, and the exact error string on failure. Annotations already flag destructive/non-idempotent, and the description enriches that with the concrete destruction mechanism.

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 sentences with no filler; the destructive-consumption warning is front-loaded right after the purpose. Slightly redundant in restating the ID provenance and the return shape together, keeping it just under 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?

With no output schema, the description supplies the success shape ({ ok, data: { id, value } }) and the failure shape, plus the destruction semantics an agent needs before calling a one-shot destructive read. Nothing material 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 description coverage is 100% and the single `id` parameter is already documented there as the opaque, case-sensitive ID from tunnel_create. The description echoes this without adding format or validation detail, 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 and resource ('Fetch the value stashed by a prior tunnel_create call by its ID') and ties itself to the sibling that produces the input, so it is clearly distinguishable from tunnel_create/tunnel_list/tunnel_destroy.

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 consumption guidance ('Use exactly once per intended consumer') and explains the failure condition (destroyed, TTL expired, never existed). It stops short of naming alternative tools or the alternative action when a tunnel is gone, so it is clear context without 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?

Goes well beyond the annotations (which only give readOnly/openWorld/idempotent/destructive hints) by disclosing the outbound network request per call, possible provider rate-limit cost, the 'read' audit-log entry, and the guarantee the value itself is never logged. It even sketches the return JSON shape. This is rich, non-redundant behavioral context.

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 purpose and free of filler, but it is a dense single paragraph bundling usage, side effects, and return shape. All content is useful, though slightly more than is strictly necessary for a scan.

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 network-touching tool with no output schema, the description supplies the missing pieces: the side effect, the audit implication, and an inline return-shape sketch. An agent has everything needed to invoke and interpret it correctly.

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 including scope, orgId/teamId conditionals, and provider auto-detection. The description mentions providers but adds no syntax or constraint detail beyond what the schema provides, 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 ('Test whether a stored secret is still accepted by its upstream service') and explains the mechanism ('minimal authenticated request'). It also distinguishes itself from siblings by naming rotate_secret and ci_validate_secrets, so an agent can route 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?

Explicitly gives when-to-use ('confirm liveness before relying on a credential' or 'verification step after rotate_secret') and names the alternative with its selection condition ('prefer ci_validate_secrets for a batch run across every key in scope'). Nothing is left 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 already declare readOnly/idempotent/non-destructive, yet the description adds real behavioral context beyond them: it is a tamper-evidence check, it does not repair a broken chain, and it documents the return contract { ok, valid, brokenAt? }. That is substantive disclosure, not repetition.

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 in the first sentence, followed by usage and return contract. Every clause carries information and none is 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 parameterless, no-output-schema tool, the description supplies the missing return shape and the non-repair caveat, so an agent has everything needed to call and interpret it correctly.

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?

The tool takes zero parameters, so there is nothing to document and the baseline is 4. The description does not need to compensate for any parameter gaps.

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 (recompute/verify) and resource (SHA-256 hash chain over the audit log) plus exactly what is being confirmed: no event mutated, deleted, or reordered. This cleanly separates it from siblings like audit_log, export_audit, and detect_anomalies.

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 triggering contexts: 'use periodically as a tamper-evidence check' and 'whenever you suspect the audit log has been touched outside q-ring,' and clarifies it is informational and does not repair. It does not name an alternative tool (e.g., detect_anomalies) to disambiguate further, so it stops short of a 5.

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