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

Since no annotations are provided, the description carries the full burden. It clearly discloses that the action is destructive, permanent (no recycle bin), and returns a specific success message or not-found error.

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

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

The description is concise with two sentences: the first states the core function and condition, the second provides alternatives and consequences. No unnecessary words or 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?

For a simple deletion tool with one parameter and no output schema, the description covers all essential aspects: purpose, usage context, side effects, and error handling. It is fully complete.

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

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

Schema coverage is 100% as there is only one parameter 'key' with a description. The description does not add extra meaning beyond the schema, meeting the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Permanently delete a single key from encrypted agent memory.' It uses a specific verb-action ('delete') and resource ('key from encrypted agent memory'), and distinguishes from sibling tools like agent_remember (overwrite) and delete_secret (for credentials).

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

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

The description explicitly guides when to use the tool ('retract obsolete or misremembered context') and when not to ('prefer overwriting via agent_remember' for updates, use delete_secret for credentials). It also warns of destructive behavior with no recycle bin.

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?

Discloses read-only nature and describes return formats for both with and without key, including error cases. No annotations provided, so description carries full burden; adequately transparent but could add more about idempotency or side effects.

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?

Concise, front-loaded with core action, no unnecessary words. Every sentence adds value.

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 tool with one optional parameter. Covers usage, alternatives, return formats, and edge cases (empty memory, not-found). No output schema, so description adequately explains returns.

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?

Single parameter 'key' with clear description that explains behavior when omitted (list keys) and when provided (read value). Schema coverage is 100%, and description adds value beyond 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?

Clearly states it reads a value or lists keys from encrypted agent memory. Distinguishes from siblings by referencing get_project_context and get_secret.

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 advises when to use (start of agent loop, rehydration, single fact lookup) and when to prefer alternatives like get_project_context and get_secret.

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?

Discloses mutation, idempotency, and return value format. With no annotations, the description covers key behavioral traits, though it could mention failure modes or rate limits. Still, it is above average.

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 efficient sentences: first states purpose and persistence, second gives usage guidance, third covers behavior and idempotency. No wasted words.

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

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

Given simple tool with 2 fully-described parameters and no output schema, the description covers purpose, usage, behavior, parameter conventions, and return value. Sufficient for effective invocation.

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?

Adds meaning beyond schema: suggests naming convention for keys (lowercase dotted namespaces) and advises JSON-stringifying structured values. This is valuable guidance for correct usage.

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 (persist) and resource (non-secret key/value note in encrypted, on-disk agent memory). It also distinguishes from siblings by explicitly warning against using for secrets (use set_secret) and transient state (use chat scratchpad).

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 examples (recording stable agent context) and when-not-to-use (secrets, transient state) with named alternatives (set_secret, chat scratchpad).

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?

No annotations provided, so description carries full burden. It discloses read-only mode by default, destructive behavior when autoRotate=true (overwrites secrets, may break integrations), and mentions tool policy and return format.

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?

A single concise paragraph that front-loads the main action. Each sentence adds value, though slightly longer than necessary. 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?

No output schema, but description states it returns a JSON report of per-project findings and rotations. Covers all key aspects of behavior, including optional destructive action, for a multi-project 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 coverage is 100%, baseline 3. The description adds valuable context beyond schema: explains default for projectPaths (server.cwd), and warns about destructive nature of autoRotate. This extra guidance justifies a 4.

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 clearly specifies the tool runs a multi-project health pass gathering decay status, audit anomalies, and manifest gaps, with optional auto-rotation of expired secrets. It distinguishes from siblings by naming health_check, detect_anomalies, and check_project.

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 as the 'canonical agent maintenance loop' and when to prefer alternatives like health_check (single read-only), detect_anomalies (audit-only), or check_project (single-project manifest check).

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?

The description discloses that the tool is read-only and uses the most recent ~500 audit events. Since no annotations are provided, this carries the full burden. It doesn't mention potential side effects (likely none) and is sufficiently transparent.

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 concise and front-loaded, stating the core function first, followed by usage, behavioral note, and output format. It is efficient but includes useful elaborations that could be slightly condensed.

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

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

The description provides the return format (JSON structure) and actionable hints (candidates for cleanup). It covers behavior, usage, and output. However, it lacks details on prerequisites like permissions or error conditions. With no annotations or output schema, it is mostly complete.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add extra semantics beyond the schema, such as how parameters affect the analysis. 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?

The description clearly states the tool cross-references secrets with audit events to produce a usage profile and suggestions. It distinguishes from siblings by explicitly mentioning that health_check is for decay-only triage and audit_log for inspecting a single key timeline.

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

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

The description provides explicit usage guidance: use as a quarterly hygiene check or input to a planner. It also gives clear alternatives: prefer health_check for decay-only triage and audit_log for single key timeline.

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?

No annotations are provided, so the description carries the full burden. It discloses the read-only nature, the output format (one line per event, formatted with timestamp/action/key/scope/env/detail), and the behavior when no events match ('No audit events found'). It does not cover rate limits or auth requirements, but for a query tool this is sufficient.

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 about five sentences, front-loaded with the purpose and usage guidelines, and every sentence adds value. It is concise and well-structured, with no wasted words.

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

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

Given no annotations, 3 parameters, and no output schema, the description covers purpose, usage, output format, and edge case. It could clarify the order of events (chronological vs. newest-first limit) but is otherwise complete. The output format is explicitly described, compensating for the lack of output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new meaning beyond the schema for the parameters themselves; it mostly repeats what the schema already says (e.g., 'limit to events touching this exact key', 'Maximum events to return, newest first'). The description adds overall output context but not parameter-specific 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?

The description clearly states the tool queries the audit log, a tamper-evident record of secret accesses. It specifies the verb ('Query') and resource ('q-ring audit log'), and distinguishes from siblings by explicitly naming `detect_anomalies` and `health_check` as alternatives.

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

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

The description provides explicit when-to-use scenarios ('investigate who accessed KEY recently?', feed an agent an access timeline) and when-not-to-use alternatives ('prefer detect_anomalies for automated unusual-pattern detection and health_check for decay-state-plus-anomalies'). It also declares the tool is read-only.

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?

Description declares 'Read-only', specifies return JSON structure and error condition, which is thorough given no annotations. Slight lack of detail on potential side effects, but 'Read-only' suffices.

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?

Description is well-structured with front-loaded purpose, but includes a run-on sentence; all content is relevant and useful.

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, return format, error case, and relation to sibling. Adequate for a moderately complex tool with 5 parameters and no output schema.

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

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

Schema covers 100% of parameters with descriptions; description adds error context for missing params but does not substantially enhance parameter understanding beyond the schema.

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

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

Description states the tool asks whether an action is allowed by policy, which is a specific verb+resource. It distinguishes from sibling 'get_policy_summary' by noting it checks single actions vs. 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?

Explicitly states when to use (as dry-run before blocked calls) and when not to ('prefer get_policy_summary for a one-shot overview'), providing clear context and 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?

With no annotations provided, the description carries the full transparency burden and does so well. It explicitly states read-only behavior, notes the minimally invasive audit effect, details the JSON return shape including the meaning of 'ready', and gives the exact error when no manifest exists.

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 dense sentences cover purpose, when to use, read-only safety, return format, and error behavior with no fluff. Information is front-loaded and 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 the tool has one optional parameter and no output schema, the description supplies all necessary context: usage, alternatives, safety profile, exact return fields, readiness semantics, and failure mode. Nothing important 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 schema already fully describes the single optional parameter, including its absolute-path requirement and default behavior. The description adds project-level context but does not materially enhance parameter understanding beyond what the schema provides, 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?

The description clearly states a specific action: compare manifest-declared keys against actual keyring contents. It also frames the tool as the canonical 'is this project ready to run' gate, which distinguishes it from broader or multi-project sibling tools like health_check and agent_scan.

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 usage scenarios are given: before starting a dev server, deploying, or onboarding a teammate. It also names alternatives and when to prefer them: health_check for scope-wide decay without a manifest, and agent_scan for multi-project scans with auto-rotation.

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

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

With no annotations provided, the description carries the full burden. It discloses side effects (outbound requests per secret, read audit events), return structure, and a special case ('No secrets to validate'). It lacks explicit mention of error handling or timeouts but is otherwise transparent.

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 concise (6 sentences) and well-structured, front-loading purpose, then usage, side effects, and return format. Every sentence adds value 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 no output schema, the description provides a clear outline of the return JSON. It covers side effects and usage scenarios. However, it does not mention required permissions or dependencies, which would be helpful for a batch operation.

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 parameters thoroughly. The description adds minimal additional meaning, only implicitly referencing scope in the purpose. Thus 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?

The description uses a specific verb-resource combination ('Validate every accessible secret') and distinguishes from sibling `validate_secret` by emphasizing batch operation and scope. It clearly defines what the tool does.

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

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

The description explicitly states when to use this tool (CI gate, pre-rotation health pass) and when to use the alternative (`validate_secret` for a single key). This provides clear guidance for the AI agent.

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?

Discloses destructive nature, no built-in trash, writes audit log, fires hooks, and returns success or not-found error. This is comprehensive given no 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?

Single paragraph with dense information; front-loaded with main action. Slightly unstructured but efficient; every sentence contributes value.

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, side effects, and return value. Lacks details on dependency handling but is adequate for a destructive tool with 5 params and no output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds an example for 'key' but does not significantly extend meaning beyond schema descriptions.

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

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

The description clearly states it permanently removes a secret value and all its env states. It distinguishes from siblings like disentangle_secrets, remove_hook, and 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?

Explicitly says when to use (credential retired or created in error) and lists alternative tools for different scenarios. Also notes it is not undoable.

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?

No annotations provided, but the description states 'Read-only; never mutates secrets or the audit log' and describes the output format: 'Returns one line per finding formatted `[type] description`, or "No anomalies detected"'. This adequately discloses behavioral traits for a read-only operation.

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 concise (4 sentences) and front-loaded with purpose. Each sentence adds distinct value: purpose, usage guidance, safety, and output format. No wasted words.

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

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

Given the simple tool (1 optional parameter, no output schema, no annotations), the description provides everything needed: purpose, usage, safety, and return format. It is complete for an agent to select and invoke 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 has 100% coverage for the single parameter `key` with a clear description. The description reiterates the parameter's purpose but does not add new meaning beyond the schema, so a baseline score 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?

The description clearly states the verb 'Scan', the resource 'audit history', and specific behaviors like 'burst reads of the same key, off-hours access'. It distinguishes the tool from siblings by naming alternatives (`health_check`, `agent_scan`) and their 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?

Explicit guidance: 'Use as a quick triage signal when investigating a single key or before letting an agent rotate credentials; prefer `health_check` for a scope-wide decay+anomaly summary, and `agent_scan` for multi-project JSON reports with optional auto-rotation.' This clearly states when to use and when not to use.

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?

Description discloses read-only nature, priority order of checks, and return format. Annotations are absent, so description carries full burden; it provides good but not exhaustive detail.

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

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

Two sentences, front-loaded with purpose. Every sentence adds essential information without waste.

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

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

Given one optional parameter and no output schema, description fully explains return format and resolution priority. Complete for a simple detection 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 covers 100% of parameters with descriptions. Description adds value by noting default behavior of projectPath, which is not in the schema.

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

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

Description clearly states the tool resolves an environment slug, using the verb 'Resolve' and specifying the resource. It distinguishes from siblings like get_secret by noting when to prefer explicit env.

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 (before reading secrets to mirror auto-picked env) and when not to (when env is already known, prefer passing explicit env). Also mentions use for logging or passing through.

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?

Description discloses that it mutates only metadata, is safe and idempotent, and returns a specific message. Also mentions subject to tool policy. No annotations provided, so description fully covers behavioral traits.

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?

Description is concise with three sentences: purpose, usage, behavior, and return format. No unnecessary words, front-loaded with the main action.

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?

Description covers when to use, how it works, safety, idempotency, return value, and policy note. Given no output schema, it adequately explains what the agent can expect.

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% with descriptions for all 6 parameters. The description does not add significant new meaning beyond the schema; it only restates that sourceKey and targetKey are the previously linked pair.

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?

Description clearly states it breaks the sync link between two previously entangled keys. This is a specific verb and resource, and it distinguishes from sibling tools like entangle_secrets and delete_secret.

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 (when a key is being retired or should diverge) and pairs with delete_secret for erasure, or entangle_secrets to recreate the link. Provides clear guidance on 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?

With no annotations, description fully discloses behavior: only mutates metadata, values unchanged, idempotent, subject to tool policy, returns short confirmation. No contradictions.

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?

Concise, front-loaded with purpose, each sentence adds value (use case, alternatives, behavior, return format). No unnecessary 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?

Covers purpose, usage, behavioral traits, return format, and idempotency. No missing critical info given tool complexity (6 params, scopes, no output schema).

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining high-level semantics (linking across scopes, default scopes, project paths default to cwd). Provides example STRIPE_SECRET_KEY.

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?

Description clearly states it links two keys across scopes so future writes propagate the same value, with specific use case example (STRIPE_SECRET_KEY). It distinguishes from siblings like set_secret and disentangle_secrets.

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 (prevent drift for same logical credential), when not to use (prefer set_secret for unrelated values), and alternative tool (disentangle_secrets to reverse). Also notes idempotency.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool reads values (records 'read' audit events), collapses superposition, returns raw .env text with warnings for missing/expired/stale keys, and handles missing keys as commented-out placeholders. This is thorough behavioral disclosure beyond the input 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?

The description is a single well-structured paragraph, front-loaded with purpose, followed by usage guidelines and behavioral details. Every sentence earns its place with no redundancy or wasted words.

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

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

Given no output schema, the description explains the return value and format comprehensively (raw text with warnings). It covers key aspects like audit events and superposition. A 5 would require explicit format specification, but the description suffices for most use cases.

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% (both parameters described). The description adds marginal value by mentioning defaultEnv in context, but does not provide additional meaning beyond the schema's descriptions. 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?

The description clearly states the tool's purpose: 'Render a complete .env file body from the project's .q-ring.json manifest, resolving each declared key from the keyring.' It uses a specific verb (render) and resource (.env file body), and distinguishes itself from sibling tools like export_secrets and exec_with_secrets.

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 provides when to use this tool ('Use when a build step or local runtime needs a real .env materialized on disk and you want exactly the keys the manifest declares') and when to prefer alternatives ('prefer export_secrets when you want every key in scope' and 'exec_with_secrets to inject secrets'). This offers clear context and exclusions.

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

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

With no annotations provided, the description carries the full burden and delivers richly. It discloses that it spawns a real child process with arbitrary side effects ('writes, network, exec'), that output is scrubbed against injected secrets, that both tool and exec policies gate usage, and details the return format ('Exit code: N' then STDOUT/STDERR blocks). The profile parameter description adds critical caveats (restricted is NOT a real OS sandbox, PATH not restricted).

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 substantial sentences, front-loaded with the verb+action and distinguishing features. The second sentence adds essential caveats. It's dense but every clause earns its place — the only minor deduction is that it's fairly long and the redaction/return-format details could arguably be tightened.

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 high-complexity tool (9 params, multiple security modes, side effects, policies, output scrubbing) with no annotations and no output schema, the description is remarkably complete. It covers return format, behavioral caveats, policy constraints, and sibling differentiation entirely in text. Nothing critical is left unexplained for an agent to safely invoke this dangerous 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by reinforcing the 'prefer env_generate/validate_secret' distinction and explaining the exec-policy gating on `command`. However, it does not enumerate parameter-specific semantics beyond what the schema already states (e.g., it doesn't detail the profile tradeoffs in the main body — those live only in the schema's profile description). Slightly above 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?

The description begins with '[exec] Run a child shell command with project secrets injected as environment variables and any leaked secret values redacted from captured stdout/stderr' — a specific verb (Run), explicit resource (child shell command with secrets injected), and the defining behavioral trait (secret redaction). It clearly distinguishes from siblings like env_generate (write .env to disk), validate_secret (liveness checks), and get_secret/list_secrets (read-only access), naming alternatives 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?

Provides explicit when-to-use ('let an agent run a script that needs credentials... without ever putting plaintext values in the chat'), explicit prefer-alternatives ('prefer env_generate if you need to write a .env file to disk and validate_secret for upstream liveness checks'), and clear exclusions ('Subject to BOTH tool policy and exec policy'). This is textbook usage 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?

Description discloses read-only nature, direct text return (no JSON wrapper), format behaviors (jsonl one per line, json array, csv header+rows), and time filter application. Lacks mention of size limits or error handling, which is acceptable given tool simplicity.

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?

Description is concise (5 sentences), front-loaded with purpose, then usage guidance, then format details. No redundant or filler content. Each sentence adds value.

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 export tool with no output schema, description fully explains return format, parameter behavior, and usage context. Includes sibling references and typical workflows, making it comprehensive.

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% with descriptions, but the description adds meaningful context: explains format nuances (stream-friendly jsonl, spreadsheet-friendly csv) and states 'Time filters are applied to event timestamps before formatting,' which clarifies processing order beyond 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?

Description clearly states it exports audit log as portable text artifact for archiving or SIEM feeding, and distinguishes from sibling tools: `audit_log` for in-conversation tail and `verify_audit_chain` for integrity check before export.

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 lists use cases (compliance exports, after-the-fact investigations, non-MCP consumer hand-off) and when alternatives are better (prefer `audit_log` for tail, `verify_audit_chain` before exporting).

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

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

Despite no annotations, describes key behaviors: collapses superposition for env, writes audit events, returns raw text (no JSON wrapper), errors on no matches, and warns about plaintext. This fully compensates for missing 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?

Single paragraph, ~100 words, well-structured: purpose first, then usage guidance, then behavioral details. Every sentence adds value with no fluff.

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 all essential aspects for an export tool: input filters (keys, tags, scope), output format, error handling, audit logging, and security. No output schema required since returns raw text, and description clarifies that.

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 minimal parameter-specific info beyond the schema (e.g., 'collapses superposition' for env, output format options already in schema). No extra semantics for other parameters.

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 clearly states the tool renders multiple secrets as .env or JSON, with specific verb 'Render' and resource 'secrets'. It distinguishes from siblings env_generate and teleport_pack by naming them explicitly.

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

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

Provides explicit when-to-use ('one-off export or copy') and when-not-to-use scenarios (prefer env_generate for manifest-driven output, teleport_pack for encrypted bundles). This guides the AI agent to select the right tool.

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

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

Despite no annotations, the description elaborates on cryptographic randomness, side effects (one write event when saveAs is provided), and return formats. However, it lacks details on error handling or security permissions needed.

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 a single dense paragraph that efficiently conveys purpose, usage, and behavioral details without waste. It could be slightly more structured but remains clear and compact.

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 8 parameters, no output schema, and no annotations, the description covers generation, storage, format variations, and return values. It lacks error scenarios and rate limits but is otherwise thorough for agent decision-making.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by grouping parameters and explaining conditional behavior (e.g., scope requirements, saveAs effect), but does not introduce new parameter details beyond the schema.

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

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

The description clearly states that the tool generates a cryptographically random secret using Node's CSPRNG and optionally stores it. It explicitly distinguishes from sibling tools rotate_secret and set_secret by specifying 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?

The description provides explicit guidance on when to use this tool: 'Use to create new credentials that you control' versus 'rotate_secret' for issuer-issued credentials and 'set_secret' for existing values. It also clarifies the read-only vs mutating behavior based on whether saveAs is provided.

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?

Even with no annotations provided, the description discloses key behavioral traits: it is read-only, returns pretty-printed JSON, and handles a missing policy file by returning an empty/default summary instead of throwing an error. This gives callers confidence in side-effect-free operation and predictable failure behavior, going well beyond the 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?

The description is three sentences, each earning its place: purpose and content, usage guidance with alternative, and behavioral notes. It is front-loaded with the core purpose and contains no redundant or vague wording.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all essential aspects: what it returns (counts and requirements), how to use it, safety (read-only), output format, and error behavior. It is complete enough for an agent to invoke correctly and interpret results.

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 projectPath parameter, so the baseline is 3. The description does not add extra parameter-specific semantics beyond referencing the governance policy file, but it doesn't need to since the schema already explains the parameter's purpose and default behavior.

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 clearly states the tool returns a high-level summary of the project's .q-ring.json governance policy, listing specific content such as counts of allow/deny rules, key reads, exec commands, and approval/rotation requirements. It distinguishes itself from the sibling check_policy by explicitly noting to prefer that tool for precise per-action verdicts.

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

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

The description provides explicit when-to-use guidance: to orient an agent on active guardrails before attempting policy-restricted actions. It names the alternative tool (check_policy) and clarifies the division of labor, which is exactly the kind of usage guidance needed.

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

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

No annotations provided, so description carries full burden. States 'Read-only and value-safe — no plaintext secret values are ever included.' and warns shape may grow, read defensively. Lacks details on rate limits or errors but covers key safety.

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?

Single paragraph with clear front-loading of purpose, then alternatives, safety, and growth note. Every sentence is necessary and adds value.

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 4 parameters all documented in schema and no output schema, description explains output contents adequately and warns about evolving shape. Slightly missing specifics on pagination or size limits, but sufficient for typical use.

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%, baseline 3. Description does not add meaning beyond schema for parameters; it focuses on output. No extra parameter context provided.

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?

Description clearly states the tool returns a 'redacted snapshot' of project context, listing specific items (secrets, env, manifest, etc.). It distinguishes from siblings by naming alternatives: list_secrets, check_project, 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?

Explicitly says to use this as the very first call to orient the agent, and provides when-not-to-use guidance by preferring listed alternatives for specific needs.

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

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

With no annotations, the description fully discloses side effects: collapses superposition, writes audit log event, and potential policy denial. It lacks explicit mention of idempotency or rate limits, but for a read operation these are less critical. The disclosure is thorough and adds value beyond the 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?

The description is a single paragraph but front-loads purpose and usage, then covers side effects and return format. It is concise with no redundant sentences. A slight structure improvement (e.g., bullet points) would elevate it, but it's already clear and efficient.

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 6 parameters, no annotations, no output schema, and many siblings, the description covers: purpose, usage guidance, side effects, return format (`{ ok, data: { key, value } }`), and error handling. Completely fills the gaps left by structured fields.

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

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

Schema coverage is 100%, so each parameter is already well-documented. The description adds minimal new parameter information (e.g., the concept of 'collapse superposition' for env is partly in schema). Baseline 3 is appropriate since the description does not significantly enhance parameter understanding beyond the schema.

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

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

Clearly states 'Read the plaintext value of a single secret' using a specific verb and resource. Distinguishes from siblings like inspect_secret, has_secret, and exec_with_secrets by naming them and contrasting their use cases. No ambiguity.

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 'Use when an agent needs the actual credential' and provides three alternatives with clear reasons to prefer each. Also mentions policy denial as a possible outcome, giving complete usage context.

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

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

Discloses read-only nature, no audit log recording, decay-awareness (returns false for expired secrets), and exact return format ('true' or 'false'). Since no annotations provided, description carries full burden and meets it excellently.

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?

Description is well-structured with front-loaded purpose, usage guidance, alternative suggestion, behavioral notes, and return format. Each sentence adds unique value, 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 5 parameters (1 required) and no output schema, the description covers core behavior, return type, audit implications, decay-awareness, and usage scenario, making it fully informative for an agent.

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. Description adds context but no new parameter details beyond schema. The example of 'GITHUB_TOKEN' and explanation of scope are present in schema already.

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 clearly states the tool checks secret existence without reading the value, specifying the verb 'check' and resource 'secret existence'. It distinguishes from sibling `inspect_secret`, which provides metadata.

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 recommends use as a cheap precondition before read/write, with an example of skipping prompts. Also suggests preferring `inspect_secret` when metadata is needed. Lacks explicit when-not-to-use, but context is clear.

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

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

No annotations exist, so description carries full burden. It explicitly declares 'Read-only — never writes,' and describes the return format in detail (header counts, issue lines, anomaly lines). This gives full transparency on behavior and output.

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 well-structured with purpose first, then usage guidance, then behavioral note, then output format. Every sentence adds value, though slightly verbose. Could be trimmed slightly but 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 4 optional parameters, no required, and no output schema, the description adequately explains the tool's function and return format. It covers the main use case and output structure. Lacks error/edge case details but is sufficient for a health check 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 coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions. It uses the parameter concepts implicitly (scope) but does not elaborate on syntax or format beyond schema.

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

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

The description clearly states the tool's verb ('Run a single read-only sweep'), resource ('every secret in the requested scope'), and output ('counts of healthy/stale/expired secrets plus any current audit anomalies'). It distinguishes from siblings by naming `check_project`, `detect_anomalies`, and `agent_scan`, giving specific differentiators.

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 as default 'is everything OK?' command and provides clear when-not-to-use: prefer `check_project` for manifest compliance, `detect_anomalies` for audit-only, `agent_scan` for multi-project JSON. This provides strong guidance on 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?

With no annotations, the description fully discloses behavioral traits: mutates keyring, emits audit events per write, supports dotenv syntax, dry-run mode, and return summary. No contradictions.

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?

Concise and well-structured; each sentence adds value. Slightly long but appropriately detailed for a batch import 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?

Covers purpose, usage, behavior, return format, and dry-run mode. Missing error handling for malformed input, but otherwise comprehensive given no output schema.

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

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

Schema coverage is 100% with detailed per-parameter descriptions. The tool description adds overall context but does not significantly enhance individual parameter meaning beyond what the schema provides, so baseline 3.

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

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

The description clearly states the verb ('Parse... and store') and resource ('dotenv-formatted text... into the keyring'), and distinguishes from siblings by naming set_secret for single keys and teleport_unpack for encrypted bundles.

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 tells when to use ('migrating an existing .env file or onboarding') and when not ('prefer set_secret... teleport_unpack'), providing direct 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?

Despite no annotations, the description fully discloses read-only nature, that it does not create a read event, and describes error behavior (not-found). It also lists all return fields, providing complete transparency.

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?

Single, well-formatted sentence packs purpose, usage, behavior, and return format without redundancy. 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?

No output schema is provided, but the description enumerates all return fields. Given parameter richness (schema covers all) and lack of annotations, the description is complete and self-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%, so baseline is 3. The description adds minimal meaning beyond schema descriptions (e.g., reiterating that orgId is required only when scope='org'). It does not provide new 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?

The description clearly states the tool shows full metadata for a single secret without revealing the value. It uses specific verbs ('Show full metadata') and explicitly distinguishes from siblings like get_secret, list_secrets, 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?

Provides explicit guidance on when to use this tool (understand shape before reading, debug expiration/staleness) and when not (prefer get_secret for value, list_secrets for overview, audit_log for timeline).

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

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

Despite no annotations, the description clearly discloses that with fix:true it mutates files and writes to keyring, warns to review with git diff, and describes read-only vs mutation. Lacks authorization details but is still strong.

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?

Description is dense yet clear, front-loaded with purpose, each sentence adds value, and uses line breaks for readability.

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

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

Covers return format, different fix behaviors, sibling tool references, and parameter nuances. Missing error handling or performance details, but adequate for a 6-param tool with no output schema.

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

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

Schema coverage is 100% (baseline 3), but description adds context like 'Non-existent paths surface as scan errors' and clarifies scope defaults and requirements, going beyond schema.

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

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

The description starts with a clear verb 'Inspect' and resource 'a specific list of files for hardcoded secrets', and explicitly distinguishes from siblings like scan_codebase_for_secrets and import_dotenv.

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 ('migrate a known set of files') and when to prefer alternatives ('whole-tree audit', 'ingest an existing .env'), including the condition for fix mode.

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

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

With no annotations, the description fully discloses behavior: it is read-only, returns a pretty-printed JSON array of hook entries or 'No hooks registered' when empty. This gives the agent a clear expectation of side effects and output format.

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 concise (three sentences) and front-loaded with the verb 'Enumerate'. Every sentence adds value: purpose, usage, output format. No wasted words.

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

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

The description is complete for a no-parameter listing tool. It explains the action, returned fields, output format, and edge case (empty registry). No gaps.

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

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

The input schema has no parameters, so the description need not add param details. It correctly implies no inputs are needed. Baseline 4 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?

The description starts with 'Enumerate every registered lifecycle hook' and specifies the fields returned (match criteria, delivery type, enabled flag, description), making the tool's purpose explicit. It also distinguishes from siblings like `remove_hook` by mentioning finding the hook's `id` before removal.

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

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

The description provides explicit usage scenarios: 'Use to find a hook's `id` before calling `remove_hook`, audit what side effects are wired up, or diagnose why a hook did not fire.' This clearly guides when to use this tool versus 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?

Discloses read-only nature and return structure (JSON array of objects with name, description, prefixes). Could add details about auth or performance but sufficient for a simple list tool.

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 purpose, then usage, then return format. No fluff.

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 listing tool with no output schema, the description fully covers behavior, return structure, and usage context.

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?

No parameters, schema coverage 100%. Baseline 4 applies as description doesn't need to add parameter info.

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?

Clearly states it enumerates secret-validation providers, provides examples, and distinguishes from sibling tools like validate_secret and rotate_secret by stating its role in discovering provider strings.

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 tells when to use this tool: to discover provider strings for validate_secret/rotate_secret or to check custom provider registration. No exclusions needed.

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

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

No annotations provided, but the description fully discloses behavior: it returns metadata only ('never the values'), is read-only, and is safe to call repeatedly. Return format and fields are detailed, leaving no ambiguity about side effects or data exposure.

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-load the purpose, then provide usage guidance and return format. No unnecessary words, well-structured for quick understanding.

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 8 parameters and no output schema, the description covers purpose, usage, return structure, and field meanings. It lacks only minor details like pagination or error conditions, which are often handled by the schema or assumed for list operations.

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 does not add extra parameter-level meaning beyond what's in the schema. It effectively explains the overall behavior but does not deepen parameter understanding.

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 clearly states 'List secret keys and quantum metadata in the requested scope, never the values.' It distinguishes from sibling tools like inspect_secret, analyze_secrets, and health_check, making its unique purpose 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?

Explicit guidance: 'Use to discover what secrets exist before reading or writing' and pairs with alternative tools for different needs. States 'Read-only; safe to call repeatedly,' providing clear context for when to invoke.

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?

No annotations provided, but the description fully discloses mutation side-effect ('Mutates the hook registry on disk'), return value ('Returns JSON...including its assigned `id`'), and error behavior. Explains trigger mechanism and delivery details.

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-structured: starts with purpose, then usage guidelines, then behavioral details. No redundant sentences; each sentence adds value. Appropriate length given tool complexity.

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 or annotations, the description covers purpose, behavior, error conditions, return value, and parameter relationships. Complete for a complex tool with 11 parameters.

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% with detailed descriptions, so baseline is 3. The description adds extra context by explaining conditional requirements (e.g., 'Pick at most one of...') and combining filters, justifying a 4.

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 clearly states the tool registers a side-effect hook that fires on secret lifecycle events. It distinguishes from siblings like `agent_remember` and `agent_scan` by specifying 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?

Explicit guidance on when to use this tool vs alternatives (e.g., 'prefer `agent_remember` for storing facts...'). Also notes the requirement for at least one match criterion.

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

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

With no annotations, the description fully bears the transparency burden. It discloses that the tool only mutates the hook registry, does not affect secrets or audit logs, is idempotent in spirit (returns error on absent id), and specifies the success output.

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 succinct, uses clear terminology, and is structured with the key action at the start, followed by usage context and behavioral details. Every sentence adds value.

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 simplicity (one parameter, no annotations, no output schema), the description covers all necessary aspects: purpose, usage, behavior, limitations, and return indication. It is fully adequate for an agent to invoke 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% for the single parameter, and the description merely repeats the schema's description. No additional semantic value is provided beyond what the schema already offers, 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?

The description uses a specific verb ('Detach') and resource ('single lifecycle hook'), clearly distinguishing the tool's purpose. It also differentiates from sibling tools by mentioning alternatives like `delete_secret` and `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?

The description explicitly states when to use this tool ('to retire a specific webhook/command without touching any secrets') and provides clear alternatives for other operations, making it easy for an agent to decide.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool mutates the keyring with a new value (one write audit event), makes outbound network requests to the provider's rotation API, and returns a specific JSON format. It also notes that if rotated is false, the existing value is left untouched. Could mention error handling more explicitly, but overall transparent.

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 a single paragraph but well-structured: begins with a [validation] tag, then action, usage guidelines, behavioral notes, and return format. Every sentence adds value, but the structure could be slightly improved with separation of concerns.

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 no output schema, the description provides the return JSON structure. It covers usage, alternatives, behavioral impacts, and return format. All 6 parameters are documented in the schema. Minor gap: does not explicitly mention prerequisites like needing a configured provider, but that is implied.

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 all parameters thoroughly. The description adds minimal additional context beyond what is in the schema (e.g., mentioning provider auto-detection). 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?

The description clearly states the action: 'Ask the upstream provider to issue a fresh credential... and store the new value back into the keyring.' It distinguishes from siblings by referencing generate_secret for self-managed values and agent_scan for sweep-style rotation, providing clear differentiation.

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: 'when a secret is expiring, leaked, or part of a scheduled rotation.' It also provides alternatives: 'prefer generate_secret for self-managed values you fully control, and agent_scan --autoRotate for sweep-style rotation across multiple expired keys.'

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?

No annotations exist, so the description fully covers behavioral traits: read-only, honors .gitignore, returns JSON array or clean string, mentions false positives. No contradictions.

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 a verb and purpose, and each sentence contributes necessary detail. Slightly long but efficient; could be tightened slightly without losing value.

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 no output schema and no annotations, the description fully explains input, behavior, output format, and caveats. Completely sufficient for the tool's complexity.

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

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

Schema coverage is 100% for the single parameter dirPath, but the description adds meaningful context: absolute/relative to cwd, recursion, and a link to .gitignore. This adds value beyond the schema.

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

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

The description clearly states the tool scans a directory tree for hardcoded secrets using regex heuristics and entropy scoring. It distinctively separates from sibling tool `lint_files` by specifying its one-shot audit nature and when to use each.

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 (before commit/release audit) and when to prefer `lint_files` (specific files, optional auto-fix). Provides clear context and 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?

With no annotations, the description carries full burden and discloses mutation (overwrites), audit log writes, hook triggering, and policy subject. It lacks details on error handling or idempotency, but covers core behavioral traits well.

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 a single paragraph of about 4-5 sentences, covering purpose, alternatives, effects, and return format without redundancy. Slightly dense but concise and 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, no output schema, and no annotations, the description is fairly complete but could elaborate on error scenarios and return value format further. Still provides a solid overview.

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 3. The description adds value by explaining per-env superposition and rotation hints beyond schema, justifying a 4.

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 clearly states the tool creates or overwrites a single secret value with multiple options (TTL, per-env, etc.), and explicitly distinguishes from sibling tools like import_dotenv, generate_secret, and entangle_secrets.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, referencing specific alternatives for bulk import, generation, and duplication, and mentions side effects like mutation, audit logging, and hooks.

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?

Discloses key behaviors: binds HTTP server, one process-wide instance (re-running returns existing URL), never exposes secret values, returns URL string. Also notes failure on port binding errors. No annotations exist, so description carries full 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 concise yet comprehensive, with a clear front-loaded purpose followed by usage guidelines and behavior notes. Every sentence adds value 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 no output schema, the description explains the return value (URL string). It covers the tool's behavior, side effect, and safety (no secret exposure). Context signals like sibling tools and parameter count align with a complete definition.

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 parameter 'port'. The description adds context beyond the schema by noting to pick another port if 9876 is in use and that binding errors cause failure, which the schema description does not mention.

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 starts with a clear verb 'Start' and specifies the resource as a local web dashboard streaming live data. It distinguishes from siblings by contrasting one-shot text summaries (health_check/analyze_secrets) with the richer visual surface.

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 usage guidance: use when an operator wants a richer visual surface, and prefer health_check/analyze_secrets for one-shot text summaries. Also mentions side effects like singleton server and port binding behavior.

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?

Discloses that each secret value is read (audit event recorded), bundle is base64-encoded ciphertext, requires same passphrase to unpack via teleport_unpack, and returns bundle string directly. Also mentions error message. No annotations present, so description carries full burden and meets it well.

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?

Description is a single paragraph that covers all needed information without excess. Could be slightly more structured (e.g., bullet points), but it is front-loaded with purpose and alternatives.

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, behavior, return format, and error conditions. No output schema, but tool returns a simple string so not needed. Missing examples or deeper clarification on scope interaction, but overall complete for the complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extra value beyond schema: mainly reinforces that passphrase must be shared out-of-band and that omitting keys includes all secrets. No significant additional 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?

Clearly describes the tool as encrypting secrets into an AES-256-GCM bundle for transfer between machines. Distinguishes from siblings export_secrets and tunnel_create with specific 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?

Explicitly states when to use (hand off curated credentials to another developer or environment) and when not to use (prefer export_secrets for .env output, tunnel_create for ephemeral delivery). Also mentions error condition when no secrets match.

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

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

With no annotations, the description carries full burden. It discloses keyring mutation (unless dryRun), error handling for bad passphrase/tampered bundle, and output format. It also mentions 'one write event per imported secret' but could further clarify isError behavior.

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

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

The description is reasonably concise (two sentences) and front-loaded with purpose. The second sentence is dense but informative. Minor room for structuring into bullet points for clarity.

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 no output schema, the description covers return values for success, dryRun, and errors. Parameter descriptions are complete. It explains the workflow and keyring mutation. Adequate for a complex tool with 7 parameters.

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%, providing thorough parameter descriptions. The description adds minor extra context (e.g., whitespace handling for bundle) but largely duplicates schema info. 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?

The description clearly states it decrypts a bundle and imports secrets into the local keyring, using specific verb 'Decrypt' and resource 'bundle produced by teleport_pack'. It distinguishes from the packing counterpart teleport_pack.

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

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

The description provides clear usage guidance: use on the receiving machine after out-of-band passphrase exchange, and prefer dryRun=true first. It implicitly defines when not to commit blindly but does not explicitly exclude other sibling tools like 'set_secret' or 'import_dotenv'.

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?

No annotations exist, so description carries full burden. It fully discloses in-memory storage, no disk persistence, restart loss, tool policy subjection, and return format.

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

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

One dense paragraph, efficiently packed with information. Could be slightly more structured, but no waste.

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

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

For a 3-param tool with no output schema or annotations, description covers purpose, usage, behavior, parameters, and return value completely.

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 covers 100% of params, but description adds context: explains maxReads for one-shot, ttlSeconds for auto-destroy, and value never logged. Adds meaning beyond 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?

Description clearly states verb (stash), resource (secret in process memory), and action (return ID). Differentiates from sibling set_secret by specifying one-shot/short-lived use case.

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 tells when to use this tool vs set_secret, and provides context for one-time values, magic links, etc. Also notes constraints like in-memory only and lost on restart.

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

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

With no annotations, the description discloses key traits: immediate removal regardless of remaining reads/TTL, in-memory mutation, and return values including error for unknown or already destroyed IDs.

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 very concise with three front-loaded sentences that convey the action, usage, and behavior without extraneous words.

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

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

The description covers purpose, usage, behavior, and return values. It does not mention how to obtain the tunnel ID, but that is a minor gap given the one-parameter simplicity.

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 schema already describes the 'id' parameter with a suitable description. The tool description adds no extra semantics beyond what the schema provides, so it meets the baseline for 100% coverage.

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 clearly states the tool immediately removes a tunnel from memory, specifying the resource and verb. It distinguishes from sibling tools like tunnel_read and tunnel_create by noting the cancellation use case and preferring normal cleanup via maxReads/TTL.

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

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

The description explicitly advises when to use the tool (cancel before delivery, e.g., wrong recipient) and when to avoid it (let maxReads/TTL handle normal flows), providing clear context for selection.

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

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

With no annotations provided, the description carries the full burden and excels: it explicitly labels the operation as 'Read-only', describes the exact output format ('id | reads:N | max:N | expires:Ns'), handles the empty case ('the literal text 'No active tunnels''), and discloses a key behavioral constraint ('values are never included'). This goes beyond any schema info since the schema is empty.

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 compact and front-loaded: the first sentence states the core action and result, the second gives usage scenarios and an important exclusion, and the third provides the exact output format and empty response. No sentence is wasted, and the structure aids quick comprehension.

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

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

For a simple, parameterless list tool with no output schema, the description is complete: it specifies the operation, the data fields returned, the formatting, the empty case, and the read-only nature. It leaves no ambiguity about what the agent will receive or how to interpret the result.

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 has zero parameters and the schema covers all of them (vacuously at 100%). Per the rubric, a baseline of 4 is appropriate when there are no parameters; the description adds no parameter-specific details because none 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?

The description states a specific verb ('Enumerate'), a specific resource ('all currently-active tunnels in the q-ring server'), and the exact data returned ('remaining read budget and time-to-live'). It distinguishes itself from siblings like tunnel_read by explicitly noting 'values are never included in the output', making its purpose unmistakable.

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

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

The description gives clear usage contexts: 'Use to audit what is still in memory or to look up an ID you forgot.' It also implicitly warns against using this for value retrieval ('values are never included'), but it does not explicitly name an alternative tool like tunnel_read. This is clear context without a formal when-not-to-use list.

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?

Fully discloses destructive behavior, increments read counter, may auto-destroy based on maxReads, and lists error conditions (not found/expired). No annotations provided, so description carries full burden and meets it.

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

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

Two sentences, first states purpose, second covers usage and return. No fluff, every sentence adds value.

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, description provides complete return format and error messages. Covers all relevant aspects for a simple read 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 coverage is 100% and description adds minimal extra beyond schema's parameter description (only error format). Baseline of 3 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?

Description clearly states verb 'Fetch' and resource 'value by ID', distinguishes from siblings like tunnel_create and tunnel_destroy, and mentions exactly-once usage.

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 specifies 'Use exactly once per intended consumer', explains destructive-by-design nature, and describes conditions for auto-destruction. Provides error cases and return format.

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?

No annotations are provided, so the description fully carries the burden. It discloses side effects: outbound network request, potential rate-limit cost, audit logging of 'read' without logging the secret value. Sufficient for safe usage.

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 well-structured with a leading category tag [validation] and uses clear sentence breaks. It is concise given the amount of useful information, though slightly verbose in listing return 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?

Given the 6 parameters, 100% schema coverage, no output schema, the description provides return shape (JSON with fields), side effects, usage guidance, and behavioral notes. Everything an agent needs is included.

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?

Input schema already provides 100% parameter descriptions, but the description adds practical guidance (e.g., 'Force a specific provider id' and auto-detection behavior). This enhances understanding beyond the schema, though not drastically.

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?

Clearly states the action: testing whether a stored secret is accepted by its upstream service. The specific verb 'validate' and resource 'secret' are unambiguous, and the description distinguishes from sibling tools like 'ci_validate_secrets' and 'rotate_secret'.

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 tells when to use (confirm liveness, verify after rotation) and when to prefer an alternative (batch run via 'ci_validate_secrets'). This provides clear context for appropriate invocation.

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

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

With no annotations provided, the description fully bears the burden of behavioral disclosure. It states the tool is read-only, informational, does not repair, and describes the exact return format including fields and meanings. No contradictions or gaps are present.

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 concise, with each sentence adding value: it states purpose, usage context, limitations, and return format. No extraneous content or 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 no annotations, no output schema, and zero parameters, the description is complete. It covers what the tool does, when to use it, its behavioral traits, and the return structure, leaving no critical gaps for an agent.

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 has no parameters, and schema coverage is 100% (empty). Per guidelines, baseline is 4. The description adds no parameter details because none exist, which 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?

The description clearly states the tool verifies the SHA-256 hash chain over the audit log to detect tampering. It specifies the action ('Recompute' and 'confirm') and the resource ('audit chain'), and distinguishes from sibling tools like 'audit_log' and 'export_audit' by focusing on integrity verification.

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

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

The description explicitly suggests when to use the tool ('periodically as a tamper-evidence check' or 'whenever you suspect the audit log has been touched'). It also states what the tool does not do ('does not repair the chain'), implying when not to rely on it for repair. However, it does not mention alternative tools or explicitly state alternative actions, missing a point for full guidance.

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