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

With no annotations provided, the description must carry the burden of behavioral disclosure. It only states the action ('call'/'execute') without addressing potential side effects, error handling, or the dynamic and possibly dangerous nature of executing arbitrary tools. This is a significant transparency gap for an execution 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?

The description is two sentences with no redundant phrasing. The action and usage context are front-loaded, making it easy to parse and remember. Every word 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?

The tool has no output schema, and the description does not explain what the caller should expect as a return value or that arguments must conform to the target tool's schema. For a meta-execution tool, this lack of critical context makes the description incomplete.

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 both parameters ('The name of the tool to call' and 'Arguments to pass to the tool'). The tool description adds no extra parameter meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's purpose with the verb 'call' and identifies the resource as a tool by name. It also distinguishes itself from sibling tools by explicitly connecting to 'execute tools discovered via search_tools,' which separates it from search and knowledge-base functions.

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 second sentence provides direct usage guidance: 'Use this to execute tools discovered via search_tools.' This tells the agent exactly when to invoke it. It does not mention alternatives or exclusions, but for a meta-dispatch tool, the context is sufficiently clear.

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

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

Annotations are all false, so description carries full burden. It details hard-filtering logic (in-force class, excluded docs) and pending_actions behavior. Exceeds minimal disclosure requirements.

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 with front-loaded purpose, then trigger explanation, filtering details, and pending_actions note. 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 5 parameters, output schema, and sibling tools, the description provides thorough context: when to call, filtering rules, and return behavior (governing rules and optional pending_actions). No gaps remaining.

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 each parameter. The description adds context for the trigger parameter and overall purpose but doesn't significantly enhance per-parameter meaning beyond schema. 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 records a consultation and returns governing rules for the intent, with specific verb+resource. It distinguishes from sibling tools like kb_search or kb_get by emphasizing its role in pre-work consultation.

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 call before code/architectural work and explains the two trigger types. While it doesn't explicitly list when not to use it, the context is clear. No mention of alternatives but the sibling list provides contrast.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds useful context by explaining that the tool records each check to the audit log, is non-destructive, and that readOnlyHint=false is intentional. It does not contradict annotations and provides behavioral detail beyond the structured fields.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by key behavioral context and explicit usage guidance. Every sentence earns its place and there is no fluff 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?

With an output schema present and detailed parameter schemas, the description covers the essential purpose, behavior, and usage context. It does not detail output semantics, but the schema handles that; the description is sufficiently complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description mentions 'pending code action' and 'specific pending action,' which loosely aligns with tool_name and action_diff, but it does not add significant parameter-level detail 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 opens with a specific verb and resource: 'Return a verdict (allow | consult_required) for a pending code action.' This clearly states what the tool does and distinguishes it from siblings like kb_consult and kb_search.

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 is provided: 'Use this in a PreToolUse hook to verify a specific pending action before execution; use kb_consult instead when proactively reading governing rules at the start of a session rather than checking individual actions.' This clearly states when to use this tool versus the key alternative.

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?

Beyond the readOnly/idempotent annotations, the description deeply explains behavior: full content markdown plus metadata, handling of expired documents with validity and freshness, and the specific differences between verbose=false and verbose=true including which fields are dropped/kept and the computed in_force predicate.

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 for the level of richness it provides. It is front-loaded with the core purpose, then usage, then detailed envelope behavior. Each sentence earns its place; nothing is redundant or filler.

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

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

Given the tool's complexity and the presence of an output schema, the description covers all essential aspects: return content, metadata, edge cases like expired documents, and the computed in_force field. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Even though the schema has 100% coverage for both parameters, the description adds significant meaning, especially for the verbose flag. It details exactly what the compact response includes/omits and contrasts with the verbose envelope, providing far more insight than the schema's 'true includes all fields.'

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 specific verb+resource: 'Retrieve a document by id' and provides concrete id examples. It clearly differentiates from sibling tools by explicitly stating 'use kb_search instead when you need to find a document by topic.'

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?

This description gives explicit when-to-use guidance: 'Use this when you have a specific id (from kb_search results or session memory)' and the alternative 'use kb_search instead when you need to find a document by topic.' It also notes the always-resolves behavior for expired documents.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds detail on response fields, conditional inclusion of pending_actions, and verbose behavior, providing full transparency beyond annotations.

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

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

The description is well-structured with purpose stated upfront, followed by parameter details and special field notes. It is concise yet informative, though it could be slightly more terse.

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 with one parameter, rich annotations, and an output schema, the description covers return fields, parameter behavior, and conditional items completely 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% with a clear description of the verbose parameter. The description adds examples of omitted fields in compact mode, enhancing 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?

The description clearly states 'Return service health' and lists specific fields like kb_commit, index_built_at, etc. It distinguishes from sibling tools (e.g., kb_search, kb_audit) which have different purposes.

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

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

The description explains when to use verbose=true vs false and advises handling pending_actions only with operator confirmation. It does not explicitly compare to alternatives, but the use case is implied.

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?

Beyond the annotations, the description clarifies the operation is non-destructive and durable, explains the meaning of event_type values, and notes required vs optional parameters. It also recommends 'reason' for bypass entries. No contradictions with annotations.

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

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

The description is concise and well-structured: it front-loads the purpose, then details parameters and usage, and ends with sibling alternatives. Every sentence adds value with no redundancy.

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

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

With an output schema present, the description need not explain return values. It covers purpose, parameter semantics, when to use, and alternatives, providing complete context for an agent to select and invoke the tool correctly.

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

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

The input schema already covers all parameters at 100%, but the description adds significant meaning by explaining event_type options (gate_bypass vs. gate_degraded) and the recommendation for 'reason' in bypass scenarios, going beyond simple 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 states a specific action ('Append') and resource ('durable, non-destructive audit entry') for client-reported enforcement events. It also distinguishes from siblings by explicitly referencing kb_gate_check, kb_consult, kb_audit, and kb_compliance.

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 the tool ('Use this when an enforce hook bypassed or degraded the gate') and provides clear alternatives for gate status, consultation, and reading back events, making the usage context unambiguous.

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 goes far beyond annotations (readOnlyHint, idempotentHint) to explain complex behaviors: hard-filtering vs downranking for in_force, default exclusion of expired docs, abstention logic, and compact vs verbose response shapes. No contradictions with annotations.

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

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

The description is well-structured, starting with a clear purpose and then explaining each parameter. Though lengthy, each sentence adds necessary detail for a complex tool with 11 parameters.

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 complexity (11 parameters, output schema exists), the description covers all parameter semantics, interactions, and return variations, leaving no gaps for effective 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?

With 100% schema description coverage, the baseline is 3, but the description adds significant value by explaining parameter interactions (e.g., in_force composing with status), the effect of include_expired on validity_state, and detailed output shape changes with verbose.

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 'Full-text search across the KB' and distinguishes the tool from siblings like kb_get and kb_list by detailing unique filtering capabilities and behavioral nuances such as in_force, abstain, and verbose modes.

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?

Extensive guidance is provided for each parameter (e.g., when to use in_force vs include_expired, abstain behavior), but there is no explicit mention of when to use this tool versus alternatives like kb_audit or kb_list for non-full-text queries.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds the format of the summary (N committed, M demoted-to-pending, K rejected) and references the feedback loop context, which adds useful behavioral insight beyond annotations.

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

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

Two sentences, clear and front-loaded with the summary. The issue reference (#112) adds minor noise but doesn't harm clarity. Could be slightly more concise, but overall 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?

With high schema coverage, annotations, and an output schema (present), the description provides sufficient context for a simple parameter tool. It explains the purpose and usage scenario adequately without needing to detail 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?

Schema description covers the one parameter (source_session) fully. Description doesn't add extra semantics but restates it implicitly by context. Baseline 3 is appropriate as schema does the work.

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

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

Description clearly states 'Read-only per-session write summary' and lists the counted categories (committed, demoted-to-pending, rejected). It distinguishes from sibling `kb_pending` and implies a specific scope per session, making the tool's 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?

Explicitly states when to call: 'whenever a write response indicated a demotion, to confirm the current tally before informing the operator.' Also names an alternative (`kb pending`) and provides a specific context (issue #112 feedback loop).

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 must carry the behavioral disclosure burden. It states the tool searches and returns ranked tool definitions, conveying a read-only operation. It adds useful context about ranking and output format. It does not explicitly mention side effects or limitations, but for a search tool, the implied read-only nature is clear enough.

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 two sentences, front-loaded with the action, and every word earns its place. It is concise, direct, and free of 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 simple one-parameter search tool with an output schema, the description is complete. It explains the purpose, the query mechanism, and the output format, which is sufficient for the agent to select and invoke it correctly. No critical gaps exist given the tool's 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?

Schema description coverage is 100%, so the parameter 'query' is well-documented in the schema as 'Natural language query to search for tools'. The description merely restates this ('natural language') without adding extra parameters, constraints, or examples. It does not enhance 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 a specific action: 'Search for tools using natural language.' It also specifies the output: 'Returns matching tool definitions ranked by relevance, in the same format as list_tools.' This distinguishes it from sibling tools like kb_search (knowledge base) and call_tool (execution).

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 context that this tool searches for tools, which implies usage when the agent needs to find a tool definition. However, it does not explicitly state when not to use it or name alternative tools, such as kb_search for knowledge base queries. The reference to list_tools gives some contextual hint, but no explicit exclusions.

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