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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the read-only and idempotent bullets largely restate structured data. However the description adds genuine context beyond them: sub-300ms latency, zero auth/API keys, AST-based local traversal, and the specific failure behavior (0 blast radius plus not-found notice when the symbol is absent).

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 opening sentence front-loads purpose, output, and sibling differentiation, and the Behavior/Usage sections are scannable. The only waste is the Parameters block, which duplicates the schema verbatim and could be dropped, and a Returns section that partially overlaps the output schema.

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

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

For a read-only analysis tool with full annotation coverage, complete schema, and an output schema, the description covers trigger conditions, failure mode, and performance envelope. Nothing required for correct invocation is missing; the only shortfall is that specific return-shape detail is redundant given the output schema already exists.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description's parameter list reproduces the same wording verbatim and adds no syntax, format, or resolution-order guidance (e.g. how file_path disambiguates duplicate symbol names). Baseline 3 applies.

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

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

States a specific verb+resource (calculates blast radius score, identifies downstream dependents) with an explicit scope (0-100, targeted symbol). It also names the two nearest siblings and explains the differentiating mechanism — targeted refactoring risk scoring versus import-graph mapping or complexity profiling.

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?

Contains an explicit 'When to use' (prior to editing a core interface, signature, or shared utility) and a 'When NOT to use' that routes to both named alternatives with the reason each is preferred. An agent can select among analyze_code_dependencies, audit_code_quality, and this tool without further inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, but the description adds useful operational context: zero auth/cloud credentials, sub-second execution, offline AST parsing, and clean error handling for missing symbols or files. Some statements repeat annotation semantics, which keeps it from a 5.

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

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

Well structured and front-loaded, with the differentiation statement early and clear sections for behavior and usage. It is somewhat over-formatted and repeats parameter details already present in the schema, but the length is justified by the tool's 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?

Covers purpose, sibling routing, read-only behavior, offline execution, auth requirements, performance, and error handling. An output schema exists and the description briefly notes the Markdown report format, so return-value explanation is not required in depth.

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

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

Schema description coverage is 100%, and the description largely restates the same parameter meanings rather than adding syntax, constraints, or conditional rules beyond the schema. Baseline 3 is appropriate when the schema already documents all 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?

States the specific analyses performed (imports, call chains, PageRank, dead code) and explicitly distinguishes itself from analyze_change_impact and enforce_architecture_rules. An agent can identify the tool's scope and sibling boundaries without opening the schema.

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

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

Includes explicit 'When to use' and 'When NOT to use' sections, naming both alternatives and the exact conditions that should route the agent elsewhere. This is about as clear as usage guidance gets.

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 discloses that the tool is fully offline, requires no credentials or external linters, completes quickly, skips unparseable binary files gracefully, and returns severity-rated diagnostics with line references. These are useful operational details that the annotations alone do not provide.

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 organized and front-loads the purpose, then separates parameters, behavior, usage, and returns. However, some content duplicates the input schema and annotations rather than adding new value, so it is slightly longer than necessary.

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 a complex multi-mode audit tool with rich annotations, full schema descriptions, and an output schema, the description provides enough context for correct invocation. It covers scope, alternatives, safety profile, error handling, and expected diagnostics without needing to fully restate return structures.

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 project_root, check_type, and file_path including defaults and enum-like values. The description repeats the same parameter meanings without adding substantial semantics beyond the structured 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 states a specific verb and resource: audit_code_quality performs AST static code smell analysis, complexity profiling, duplicate detection, and hallucination validation. It also explicitly distinguishes itself from sibling tools 'verify_security_guard' and 'analyze_code_dependencies' by contrasting maintainability/complexity scanning with credential-leak checks and dependency analysis.

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

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

It gives explicit when-to-use guidance, including concrete examples such as long methods, excessive arguments, missing docstrings, copy-pasted blocks, and hallucinated imports. It also gives explicit when-not-to-use guidance and names the correct alternatives for security checks and dependency analysis.

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

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

Annotations already cover read-only, idempotent, closed-world and non-destructive, but the description goes beyond them with offline/zero-telemetry operation, no-auth requirement, a concrete performance bound (<2s for 1,000 files), and defined error behavior (Markdown warning notices when no analyzable files exist). That is real added context for a tool that walks a filesystem.

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 leading purpose sentence plus labeled Behavior/Usage Guidelines/Returns sections are front-loaded and scannable. It loses a point for re-listing all six parameters verbatim when the schema already documents them, which is filler rather than 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 six optional params, full schema coverage, an output schema, and rich annotations, the description leaves nothing material unexplained — it covers modes, token budget, error paths, and the shape of the returned Markdown tiers.

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

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

Schema description coverage is 100% and the parameter block in the description is essentially verbatim duplication of the schema entries, so it adds little beyond structured data. The only minor surplus is the '.' working-directory gloss and the compression percentages, which the schema mostly carries too.

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

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

States a specific verb+resource pair ('Scans the target repository file system and constructs an AST context payload') and immediately contrasts it with the two nearest siblings, prune_code_snippet and search_codebase, by describing what each does instead. An agent can differentiate without consulting the schema.

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

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

Has explicit 'When to use' (start of coding session or major refactor, 80-95% token savings) and 'When NOT to use' sections that name the alternative tools and the condition that selects them. No inference required.

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

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

Beyond annotations that already mark it read-only and idempotent, the description adds operational details: 100% offline validation, zero auth/API keys, <500ms completion, and error handling for missing configuration. It also clarifies that validation scans imports/call paths and produces a compliance audit report, which is meaningful behavioral context.

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

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

The description is well structured and front-loads purpose and sibling differentiation before detailed behavior and usage. It is somewhat long and repeats some annotation-backed properties and schema parameter text, but the structure keeps it readable 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?

The description is complete for a validation tool: it covers purpose, alternatives, execution profile, error handling, and expected returns. With an output schema and rich annotations also present, no critical information is missing for correct 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?

Schema description coverage is 100%, so both parameters are already well documented. The description's parameter section largely restates the schema's own descriptions for 'project_root' and 'strict_mode' without adding syntax or format details beyond them. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Enforces architectural boundary rules and layer isolation constraints') and explicitly distinguishes itself from 'manage_architecture_rules' and 'analyze_code_dependencies' by contrast of role. An agent can identify exactly what this tool does and how it differs from siblings without opening schemas.

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

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

It gives explicit when-to-use guidance ('CI/CD pipelines or before merging PRs') and explicit when-NOT-to-use alternatives for rule management and dependency inspection. The routing conditions are concrete and actionable.

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

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

Annotations already cover readOnlyHint, idempotentHint, openWorldHint and destructiveHint, so the description's 'Read-only' and 'Idempotent' lines largely restate them. It does add genuinely new context — 100% offline local pricing table, zero auth, <5ms latency, and graceful handling of empty input — which is useful. However it is internally ambiguous about export_agent_rules: it claims 'without disk modifications' yet describes exporting .cursorrules/.clinerules files, and the Returns section mentions only a markdown table, leaving the write-vs-return behavior unclear.

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

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

Front-loaded and clearly sectioned, but the Parameters block duplicates the 100%-covered schema descriptions almost word for word, and the 'Read-only'/'Idempotent' lines restate annotations. Roughly a third of the text does not earn 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?

An output schema exists, so the brief Returns note is sufficient. Inputs, behavior, error handling and sibling alternatives are all covered; the only real gap is whether export_agent_rules writes files or returns content, which matters for an agent choosing that parameter.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by enumerating valid export_agent_rules values ('cursorrules', 'clinerules', 'markdown', or empty) even though the schema declares no enum, and by clarifying that tokens is an alternative to text for direct cost calculation. Defaults are repeated verbatim from the schema, which adds little.

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

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

States specific verbs and resources: token counting, comparative API billing costs across named providers, and ROI savings. It also explicitly differentiates itself from build_project_context and prune_code_snippet by contrasting 'financial costs and token metrics' with 'constructing context trees or pruning code'.

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 an explicit 'When to use' list (forecast LLM API spend, evaluate token consumption, export rule files) and a 'When NOT to use' clause that names the exact alternative tools to use instead. An agent can route correctly without inference.

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

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

Beyond annotations, it discloses deterministic dispatch, fully offline local-AST execution, zero credentials, sub-500ms completion, graceful fallback, and a unified executive summary for action='auto'. It does not fully detail the side effects of mutation-adjacent actions like 'heal' patching or 'memory' management.

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 and organized into Parameters, Behavior, Usage Guidelines, and Returns sections. It is lengthy and includes some promotional phrasing and duplication of the action list, but the size is mostly justified by the 13-action dispatcher 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?

Given the broad dispatcher complexity and the existing output schema, the description covers action semantics, target/query/options usage, behavioral constraints, and error handling well. It leaves some per-action side-effect details implicit, especially for patching or memory mutation.

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

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

Schema coverage is already 100%, but the description adds useful semantics: action-specific meanings, how target varies by use case, how query depends on action, and example option keys such as reduction_mode, max_tokens, and depth. Much of this overlaps the schema, so it is helpful rather than fully additive.

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

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

The description states a specific verb and resource: executing codebase workflows via a unified dispatcher. It explicitly distinguishes itself from the many specialized sibling tools by acting as an autonomous orchestration layer across context, audit, security, dependencies, and healing.

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

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

It includes explicit 'When to use' and 'When NOT to use' sections, directing agents toward a unified entrypoint for complete overviews and away from isolated low-level API calls. It could be stronger if it named specific sibling tools to prefer for isolated operations.

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/openWorld=false/destructive=false, but the description adds real context beyond that: it clarifies nothing is written even though it 'generates' a document, that output is deterministic offline AST analysis, that runtime is <1s with zero credentials, and that it degrades to offline AST mapping if the AI provider is unreachable. That fallback behavior is not derivable from annotations or schema and materially affects how an agent should call 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?

The opening sentence is strongly front-loaded and carries the disambiguation, and the behavior/usage sections are scannable. There is mild redundancy: the Parameters block duplicates the schema descriptions word-for-word, and the Returns line restates what the output schema already provides.

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 three-parameter, fully-annotated, output-schema-backed tool, nothing an agent needs is missing: what it produces, what it will not do (write files), cost/latency profile, credential requirements, failure mode, and sibling routing are all present.

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

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

Schema description coverage is 100%, so all three parameters are already fully documented in the schema, and the description's parameter block largely restates those same strings verbatim. The one nuance added (offline determinism tied to use_ai=False) is behavioral rather than semantic, so baseline 3 applies.

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

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

The first sentence states a specific verb (Generates) and a concrete artifact (ARCHITECTURE.md) with its contents: Mermaid topology diagrams, layer boundaries, module hierarchies. It then explicitly contrasts with the two nearest siblings by naming what each does instead, so an agent can disambiguate without opening a schema.

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

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

Provides an explicit 'When to use' (onboarding docs, RFC review) and a 'When NOT to use' that names both alternative tools and their distinct jobs (enforce_architecture_rules for rule compliance, analyze_code_dependencies for raw dependency/call-chain data). This is textbook when/when-not/alternatives routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds valuable context beyond them: state-modifying behavior on disk, which actions are destructive, 100% offline operation, no auth/rate limits, sub-20ms execution, and JSON validation before writing. It discloses what is altered and under which actions.

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 structured and front-loaded with purpose, alternatives, parameters, behavior, and return shape. It is somewhat long and repeats schema parameter descriptions, but the information is relevant and organized.

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, the annotations covering safety profile, the fully described schema, and an output schema, the description is complete. It provides enough behavioral and usage context for correct 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?

Schema description coverage is 100%, so the schema already documents all four parameters. The description repeats the same parameter details with little additional semantics beyond echoing the schema, which meets the baseline for high schema 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 states a specific verb and resource: it manages the lifecycle of architectural boundary definitions, tier rules, and layer constraints in tzero.rules.json. It explicitly distinguishes itself from 'enforce_architecture_rules' and 'generate_architecture_blueprint' by describing its disk-mutating role versus validation and diagram generation.

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

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

It gives explicit 'When to use' and 'When NOT to use' guidance, naming alternatives and the conditions that select them. The agent does not need to infer whether to choose this tool or a sibling.

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 discloses which operations destroy on-disk data ('reset' and 'delete' remove stored memory data from disk), the idempotency split per operation, zero auth, sub-50ms latency, and error handling for unrecognized modes. The only weakness is that the tool-level idempotency statement is coarser than the per-operation reality, and no warning is given that 'reset' is irreversible/unscoped.

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

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

Front-loaded and well-sectioned with headers, but the Parameters block duplicates the 100%-covered schema verbatim and adds bulk without value, and the opening sentence is a long run-on. Roughly a third of the text is redundant given the structured fields.

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

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

For a destructive, multi-mode lifecycle tool the description covers operations, destructive semantics, auth, latency, errors, and alternatives; an output schema exists so the brief Returns line is sufficient. The one gap is the operation-vocabulary mismatch ('decompress') between description and schema, leaving the exact valid mode set ambiguous.

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 description's parameter block largely restates what is already structured. It does add the 7-value operation vocabulary, but it lists a 'decompress' operation that is absent from the schema's own operation description, creating an inconsistency an agent could trip on rather than added clarity.

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

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

The description opens with a specific verb+resource ('Manages the complete lifecycle of persistent agent semantic memory stores') and enumerates the concrete operations (compress, consolidate, export, list, reset, delete). It explicitly distinguishes itself from query_memory_store and prune_code_snippet, so an agent can route correctly without opening the schema.

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

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

Dedicated 'When to use' and 'When NOT to use' sections name the exact sibling alternatives and the conditions that select them ('querying existing knowledge triples or causal chains' → query_memory_store; 'pruning source code snippets' → prune_code_snippet). Both positive and negative routing is covered.

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

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

Adds real context beyond the annotations: non-idempotent mutation, fully offline execution, no credentials/relay, sub-100ms completion, and quorum-isolation error handling. However, 'Non-idempotent' and 'Offline' largely restate idempotentHint=false and openWorldHint=false, so part of the disclosure duplicates structured data rather than extending 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?

Sectioned with headers and front-loaded with purpose, but there is wasted space: the sibling differentiation appears both in the opening paragraph and again in 'When NOT to use', and the four-bullet parameter list is a verbatim copy of the schema. Marketing-style claims ('100% Offline', '<100ms') pad the behavior block.

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

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

For a complex, non-idempotent, multi-mode orchestration tool, the definition covers mode selection, agent role input, auth/rate-limit posture, error handling, and a returns summary. An output schema exists, so detailed return structure need not be spelled out, and the remaining guidance is sufficient to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters; the description's parameter block repeats the schema text almost verbatim, including the orchestration_mode value list. Baseline 3 applies since the schema does the heavy lifting and the description adds no syntax, constraints, or interaction rules.

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

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

States a specific verb set (coordinates, decomposes goals, runs PBFT consensus, self-heals) over a named resource (multi-agent swarm), and explicitly names the sibling tools it is not. An agent can pick this out from query_memory_store or audit_code_quality on name alone.

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' conditions (complex coding goals, consensus validation with 3f+1 quorum, test-failure healing) and a 'When NOT to use' section that routes to query_memory_store, manage_memory_store, and audit_code_quality by name. No inference required.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description partly repeats those (Read-only, Idempotent, 100% Offline). It earns credit for genuinely new behavior: zero-auth requirement, <10ms latency, supported language list, and graceful regex fallback on malformed syntax — the fallback being the most decision-relevant detail an agent cannot get from 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?

Content is well-sectioned (Parameters / Behavior / Usage / Returns), but the opening sentence is a single cramped run-on that front-loads sibling differentiation awkwardly. Several lines (Read-only, Idempotent) restate annotations and the 'Returns' line duplicates the output schema, so not every sentence earns its place.

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

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

For a 3-parameter transform tool, everything needed to invoke it correctly is present: input kinds, parser selection, reduction levels, fallback behavior. The explicit 'Returns' section is redundant given an output schema exists, and mode-selection guidance for mixed inputs is thin.

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's parameter entries are near-verbatim copies of the schema descriptions and add no format, constraint, or interaction detail beyond them (e.g. no guidance on how reduction_mode interacts with file_name_or_lang for diff inputs).

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

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

States a specific verb+resource (prune implementation bodies from code snippets/schemas/diffs) plus the invariant it preserves (AST interfaces, signatures). It explicitly contrasts with 'build_project_context' and 'audit_code_quality', so an agent can separate it from siblings without opening any schema.

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

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

Provides an explicit 'When to use' (compress code strings/diffs before LLM embedding for 80-95% token savings) and a 'When NOT to use' that names both alternative tools and the conditions selecting them. Both positive and negative routing are covered.

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

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

Annotations already declare read-only, idempotent, closed-world, non-destructive, but the description adds genuine context beyond them: offline operation, zero auth/cloud credentials, <10ms latency, and the empty-graph error behavior for missing entities. That is substantive disclosure an agent cannot get from the annotations alone.

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

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

Front-loaded with purpose and sibling differentiation, then segmented into Behavior, Usage Guidelines, and Returns. Slightly long because the Behavior bullets partially echo the annotations (read-only, idempotent), but overall efficient and well organized.

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 read-only query tool with full schema coverage, annotations, and an output schema, the description covers scope, alternatives, safety, latency, offline behavior, and error semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description's parameter list largely restates the schema text including defaults and mode meanings. Baseline 3 applies since the schema does the heavy lifting and the description adds little beyond it.

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

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

States a specific verb (queries) and specific resources (semantic triples, causal reasoning graphs, MinHash entity clusters) and explicitly distinguishes itself from 'manage_memory_store' and 'search_codebase'. An agent can route to it without opening a schema.

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

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

Provides an explicit 'When to use' list and a 'When NOT to use' list that names both alternatives and the conditions selecting them. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description's restatement of those traits adds little. However, it goes beyond annotations with genuinely new context: fully offline/CPU-only execution, zero network egress, zero auth, sub-millisecond latency, and an explicit error-handling path returning an empty report with suggestions.

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

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

Well front-loaded with the core purpose first, then structured sections for parameters, behavior, usage, and returns. Slightly verbose where it repeats annotation-backed traits (read-only, idempotent) and the return shape already covered by the output schema.

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 search tool with an output schema and full annotation coverage, the definition is complete: purpose, retrieval mechanism, alternatives, failure mode, and performance profile are all present. An agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 100% and the description's parameter list restates the schema text near-verbatim, adding no syntax, format, or behavioral nuance beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (hybrid search combining BM25 + TF-IDF) and resource (repository functions, classes, docstrings), and immediately distinguishes itself from 'query_memory_store' and 'build_project_context' by what it indexes. An agent can identify it without opening the schema.

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

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

Provides explicit 'When to use' and 'When NOT to use' sections, naming the exact alternatives (query_memory_store, build_project_context) and the conditions that select them. Nothing is left to inference.

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

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

Goes well beyond the annotations: it discloses the conditional write behavior (read-only under 'scan', writes a hook file under 'install_pre_commit'), that everything runs fully offline with zero data transmission, zero auth requirements, and sub-50ms latency, plus what errors report. This usefully reconciles readOnlyHint=false with the read-only scan mode rather than contradicting it. Only omission is what exactly gets written/where the hook lands.

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

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

Front-loaded with purpose and sibling differentiation, then cleanly sectioned into Parameters, Behavior, Guidelines, and Returns. It is on the long side and the parameter block duplicates schema text nearly verbatim, which is the only wasted space.

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?

Annotations cover safety hints and an output schema exists, so the description needn't explain return values beyond its summary line. It still supplies the operational context an agent needs: offline execution, idempotency, conditional mutation, and error reporting with line numbers and entropy scores.

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 three parameters, and the description's parameter list largely restates those same strings. It adds only minor value ('default: current directory', explicit default for content). Baseline 3 is correct since the schema carries the load.

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

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

The opening sentence names specific verbs and resources ('scans workspace files and code buffers for hardcoded secrets and API keys', 'installs the automated git pre-commit zero-leak security guard') and explicitly contrasts the mechanism against two named siblings (entropy credentials and git hooks vs. complexity or layer rules). An agent can distinguish it from audit_code_quality and enforce_architecture_rules without opening any schema.

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

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

Dedicated 'When to use' and 'When NOT to use' sections give the trigger condition (before committing or sharing context) and route each exclusion to a named alternative tool. There is no ambiguity about which sibling to pick for quality scans or architecture enforcement.

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