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

No annotations are provided, so the description carries the full burden and does so well: it declares read-only AST traversal, deterministic/idempotent results, and 100% offline local analysis with no remote services. These are exactly the behavioral traits an agent needs before invoking a static-analysis 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?

Front-loaded with the core capability, then logically grouped into Behavior, Usage, and Returns with zero filler sentences. Slight deduction because the Returns block restates a structured output that already exists as an output schema, making it mildly redundant.

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

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

For a two-parameter read-only analysis tool, the definition covers purpose, safety profile, invocation timing, alternatives, and return shape. With an output schema present, it does not need to explain return values in detail, so nothing material is missing.

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

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

Schema description coverage is 100% and both parameters are documented there (target_symbol as the symbol to analyze, project_root with a default of '.'). The description adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource+scope: calculates a blast radius score (0-100) and finds direct/transitive dependents for a function, class, or symbol. It is immediately distinguishable from siblings like trace_symbol_call_chain and query_module_dependencies 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?

Gives a concrete when-to-use trigger ('Run BEFORE renaming, refactoring, or modifying a function or class') and explicit sibling routing for two adjacent alternatives with the condition that selects each (recursive trees/Mermaid vs file-level module deps).

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 supplied, the description carries the full burden and does so: read-only ('does not modify or delete files'), idempotent ('consistent quality diagnostics for the same code'), and offline ('zero external requests'). That covers the safety, determinism, and network profile an agent needs before invoking an audit.

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 one-line purpose, then labeled Behavior / Usage Guidelines / Returns blocks. The bullets are dense and each carries distinct information; nothing is padded despite the length being justified by a multi-mode 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?

An output schema exists, so the return-value explanation is technically optional, yet the severity taxonomy (T-001 through T-004) adds useful interpretive context. Combined with complete parameter docs and full behavioral disclosure, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and both parameters (file_path, project_root) are already fully documented with defaults in the schema. The description adds scope context ('audits all code files in the workspace') but no syntax, format, or edge-case meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (performs an audit) and enumerates the four distinct analyses it runs: AST code smells, cyclomatic complexity, copy-paste duplicity, and Zero-Leak credential scanning. This clearly separates it from single-purpose siblings like find_code_duplicity or verify_zero_leak_security.

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

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

Explicit 'When to use' (pre-commit / pre-PR health audit) plus a 'Sibling Routing' block that names three alternatives and the exact condition under which each should be preferred instead. This leaves nothing to inference.

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

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

No annotations are provided, so the description carries the full burden and does so well: it declares read-only (audits AST, does not block git/mutate/modify config), idempotent, and fully offline. This is strong disclosure. It stops short of noting rate limits, error behavior, or permissions, so not a full 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 with a summary sentence, then Behavior, Usage Guidelines, and Returns sections. Front-loaded purpose, every line earns its place, no redundancy.

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

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

Complete for a codebase-audit tool: purpose, behavior traits, when-to-use, sibling routing, and return shape are all present. With an output schema existing, the 'Returns' line is a helpful summary rather than a necessity, and the description still covers everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100% for both params (rules_file, project_root), so the schema already documents defaults and resolution. The description mentions tzero.rules.json but adds no parsing detail, path semantics, or fallback behavior beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific verb (enforces) and a well-defined resource (T-4 architectural boundary rules from tzero.rules.json), plus what it verifies: modular separation and unauthorized cross-layer imports. Clearly distinguishes from siblings like query_architecture_boundaries (view rules) and audit_codebase_quality (general smells).

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

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

Explicit 'when to use' (CI/CD pipelines, before committing, to verify layer isolation) and explicit sibling routing naming two alternatives with the conditions that select them. Nothing 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?

With no annotations, the description carries the full burden and does so well: it declares read-only status ('does NOT invoke provider APIs or incur financial billing'), idempotency, and 100% offline operation with local pricing tables. It also states the return shape (a Markdown comparison table) and the $0 Ollama case, covering the safety and behavior profile an agent needs.

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

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

Front-loaded with the core purpose, then cleanly sectioned into Behavior, Usage Guidelines, and Returns. The labeled sections make it easy to scan, though the multi-line formatting is slightly heavier than strictly necessary for a three-parameter 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?

For a tool with no annotations, this covers everything needed: what it computes, that it is offline/safe/non-billing, when to use it, the sibling alternative, and a brief note on returns (output schema exists, so return detail is not required). 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 the schema already documents all three parameters, giving a baseline of 3. The description adds only a light gloss ('for a given text or directory') and does not explain reduction_mode ('ultra', 'balanced', 'none') beyond what the schema already provides.

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

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

States a specific verb+resource ('Calculates exact token count and estimated API prompting cost') and scopes it to named providers (OpenAI GPT-4o, Claude 3.7 Sonnet, Groq, NVIDIA NIM, Ollama). It also distinguishes itself from the sibling get_token_savings_metrics, so an agent can route without opening either schema.

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

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

Includes an explicit 'When to use' condition (estimating prompt/cost before sending large codebase context to commercial APIs) and an explicit 'Sibling Routing' exclusion pointing to get_token_savings_metrics for cumulative ROI tracking. Both the trigger and the alternative are named directly.

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 present, the description carries the full burden and does so well: it discloses that it is mutating, idempotent (overwrites T-Zero rule files without corrupting user customizations), and 100% offline using built-in templates. These are exactly the behavioral traits an agent needs before invoking a write 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?

Well-structured with labeled sections (Behavior, Usage Guidelines, Returns) and front-loaded purpose. Every line earns its place by conveying behavioral or routing information rather than restating the name.

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

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

Complete for a file-writing tool: mutation semantics, idempotency, offline behavior, when-to-use, sibling routing, and return value are all covered. An output schema exists, and the description still summarizes the return value, leaving nothing an agent needs 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 both parameters (target, project_root) are already documented including the target's default of 'all'. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Generates and writes standardized AI agent rule specifications') and enumerates the exact file formats produced (.cursorrules, .cursor/rules/*.mdc, .clinerules, .github/copilot-instructions.md). This is unambiguous and clearly distinct from siblings like query_architecture_boundaries.

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

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

Explicitly names when to use it ('setting up a repository for AI pair-programming with Cursor, Claude Code, Cline, Windsurf, or GitHub Copilot') and routes to the alternative ('To view architectural boundaries without writing files to disk, use query_architecture_boundaries'). The write-vs-read distinction is spelled out.

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

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

With no annotations, the description carries the full burden and does so: it discloses read-only behavior (hashes/compares, does not modify), idempotency (deterministic for any state), and 100% offline execution. These are precisely the safety/behavioral traits an agent needs.

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

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

Sectioned into Behavior, Usage Guidelines, and Returns with the core action stated first. Every line is informative rather than filler, and the structure makes it scannable.

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 static analysis tool, the description covers purpose, behavior, routing, and even the return format (markdown report with clusters, paths, line ranges, snippets). An output schema exists, so return detail is bonus rather than required.

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 both params (min_lines, project_root) with defaults. The description adds no further parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb (scans/identifies) and resource (duplicate copy-pasted code blocks across files) with the goal (refactoring opportunities). It explicitly distinguishes itself from siblings 'audit_codebase_quality' and 'find_dead_code', so an agent can route correctly without opening schemas.

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

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

Provides an explicit 'When to use' condition (refactoring sprints to locate redundant blocks) and a 'Sibling Routing' section naming the exact alternatives for adjacent tasks (quality/complexity audits and dead code). Both when-to-use and when-to-use-alternatives 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?

With no annotations, the description carries the full burden and does so: read-only (no source modification), idempotent, fully offline/local. It also discloses false-positive guards — exclusions for __all__, main, dunder methods, and test functions — which is exactly the behavioral context an agent needs.

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

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

Front-loaded one-line purpose followed by clearly labeled Behavior, Usage Guidelines, and Returns sections. Every sentence adds distinct information 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?

An output schema exists, yet the description still usefully previews the return shape (markdown report with file paths, line numbers, symbol types). Combined with the behavior and routing sections, nothing needed to call it correctly is missing.

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

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

Single parameter with 100% schema description coverage, including the default of '.'. The description adds nothing beyond what the schema already documents, so the baseline 3 applies.

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

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

States a specific verb + resource ('Finds unused, orphaned, or unreferenced functions and classes') plus the mechanism (AST). The exclusion list narrows the semantic scope and distinguishes it cleanly from audit_codebase_quality and find_code_duplicity.

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

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

Explicit 'When to use' context (technical debt cleanup for safe removal) plus named sibling routing: find_code_duplicity for duplicate logic, audit_codebase_quality for complexity/linting. An agent can route 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?

With no annotations, the description carries the full behavioral burden and does so well: read-only by default (returns markdown, does not write files unless via CLI export), idempotent/deterministic when use_ai=False, and cost/auth implications (free and local by default; uses configured API key when use_ai=True).

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

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

Front-loaded with the purpose and organized into clear Behavior/Usage/Returns sections with bullets, so it scans well. Slightly verbose and mildly repetitive (the free/local vs AI cost point is restated in Behavior and Returns), keeping it just below a 5.

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

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

For a zero-required-parameter generation tool with an output schema present, the description is complete: it covers scope, safety/write behavior, cost/auth tradeoffs, sibling routing, and even summarizes returns. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, making 3 the baseline. The description reinforces use_ai's cost/network implications and model's role, adding marginal value but no syntax or format 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?

States a specific verb+resource: generates a complete system architectural specification (ARCHITECTURE.md) with Mermaid diagrams, layer boundaries, and module hierarchies. This is distinguishable from siblings like generate_repo_map or query_module_dependencies without opening any schema.

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

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

Explicitly gives when-to-use (create/update architecture docs and diagrams for onboarding or RFC review) and provides Sibling Routing that names two alternatives with the condition selecting each ('enforce_architecture_boundaries' for rule compliance, 'query_module_dependencies' for dependency trees).

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 does so well: it declares read-only ('without writing or modifying files'), idempotent/deterministic, and 100% offline with zero external API calls. These are exactly the behavioral traits an agent needs before invoking a codebase scan.

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 purpose followed by tight categorized bullets; every line is scannable and earns its place. The 'Returns' line is mildly redundant given an output schema exists, keeping this just short of a 5.

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

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

Given an output schema exists, the description need not explain return values, yet it briefly does so anyway. Purpose, scope, alternatives, behavioral profile, and output shape are all present, leaving no gap 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 description coverage is 100%, so both parameters (max_tokens, project_root) are already documented in the schema and the description need not repeat them. It adds no format/semantics beyond the schema, which is the correct baseline-3 situation.

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

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

The description states a specific verb+resource+output: 'Generates an ultra-compressed AST symbol token map (classes, methods, functions)'. It also names the exact siblings it differs from (get_project_context_tree, get_smart_skeleton_context), so an agent can distinguish it without opening any schema.

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

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

There is an explicit 'When to use' condition (give the LLM a high-level index across the repo in minimal tokens) plus explicit 'Sibling Routing' rules that name the alternatives and the condition selecting each. Nothing is left to inference.

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

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

No annotations are supplied, so the description carries the full burden — and it does: it discloses read-only semantics ('does not stage, commit, or revert'), idempotency/determinism, and full offline/local-CLI execution. It also sketches the return shape, which is unusually thorough for a tool with zero annotation coverage.

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

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

Front-loaded with the core purpose and cleanly sectioned into Behavior / Usage / Returns, so it scans well. Minor deduction because the '98%+ token savings' claim is repeated in two sections and reads as promotional padding rather than added information.

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

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

For a two-parameter read-only diff tool, the description covers purpose, routing, behavioral guarantees, and return format. Since an output schema already exists, the inline 'Returns' note is surplus but harmless, and nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and both parameters (base_ref, project_root) carry their own defaults and descriptions, so the schema does the heavy lifting. The description adds no syntax, format, or edge-case guidance for base_ref beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Calculates hyper-compact PR git diff context' — and immediately narrows the output to 'changed symbols + downstream blast radius dependents.' The sibling-routing line makes its boundary against 'get_project_context_tree' and 'analyze_change_impact' explicit, so an agent can distinguish it without opening any schema.

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

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

Provides an explicit 'When to use' condition (code review, PR description generation, bug hunting on pending changes) and names two concrete alternatives with the condition that selects each. Nothing about tool selection 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 are absent, so the description carries the full burden, and it does so well by disclosing read-only, idempotent, and offline/no-LLM-cost traits. It omits error behavior, handling of unreadable/symlinked directories, and runtime cost characteristics, which leaves modest gaps for a repository-wide scan.

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 a one-line purpose followed by labeled Behavior / Usage Guidelines / Returns sections that scan quickly. Some jargon is inflated ('enterprise-grade multi-tier T-Zero', 'T-1 Master Architecture'), which adds words without adding agent-relevant meaning, but the structure is clean.

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 is moderately complex (4 params, AST scanning) and the description covers behavior, safety profile, usage context, sibling routing, and output shape; with an output schema present it need not detail return values. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and each parameter (max_tokens, project_root, reduction_mode, include_file_contents) is already well documented in the schema, so the baseline of 3 applies. The description only lightly reinforces this by mentioning 'up to max_tokens' in the Returns line and adds no format 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 names a specific verb and resource ('Scans the target project directory and builds ... hierarchical context tree') and immediately differentiates itself from siblings via an explicit Sibling Routing paragraph that names generate_repo_map, get_smart_skeleton_context, and prune_code_snippet with the conditions that select each. An agent can route correctly without opening any schema.

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

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

It states precisely when to use it ('start of a coding session or before large refactors') with a quantified benefit, and then provides explicit alternative routing for four distinct sibling scenarios. This is the when/when-not/alternatives pattern executed fully.

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 the full burden and does well: it declares read-only, idempotent, and 100% offline behavior, plus the token-efficiency trait. It does not address failure modes (missing file, non-parseable syntax, side effects of the focus_symbol filter), which prevents a 5.

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

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

Front-loaded with the core behavior in the first sentence and organized under Behavior/Usage/Returns headings. Some marketing phrasing ('Lost in the Middle', 'saving 95%+ tokens') adds flavor at the cost of a little density, but overall structure is tight.

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 description needn't explain return values, yet it still summarizes them as structured Markdown. Purpose, usage, siblings, and behavior are all covered; only error/edge-case handling is missing, which is a minor gap for this read-only tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's parenthetical '(or specific focus symbol)' reinforces the focus_file/focus_symbol relationship, but it adds little syntax or format detail beyond the schema and never addresses the project_root parameter's role.

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: returns the full focus file/symbol plus T-3 AST signatures of its 1st-degree imports and callers. The scope distinction (full implementation vs. compact skeletons) is precise and lets an agent differentiate it from the many other context/repo tools in the sibling list.

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' line (editing a specific file) and a 'Sibling Routing' section that names get_project_context_tree for repo-wide context and generate_repo_map for symbol-only indexes. This is exactly the when/when-not/alternatives structure.

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 full burden. It discloses read-only, idempotent, and 100% offline behavioral traits, plus indicates the return format. Missing finer details like auth requirements or what happens on invalid project_root, but the core behavioral profile is well covered.

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 purpose sentence, then clearly labeled Behavior, Usage Guidelines, and Returns sections. No filler; every line adds information an agent needs.

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

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

Output schema exists so return values needn't be detailed, yet a brief Returns summary is still helpful. Read-only/idempotent/offline behavior, sibling routing, and usage context are all present; only minor edge-case behavior is absent.

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

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

Schema coverage is 100% so baseline is 3. The description's Returns section clarifies the output depends on team_size (monthly ROI) and project_root (codebase measurement), adding meaning to how parameters affect results beyond the schema's field-level docs.

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 (computes) and precise resource (quantitative token compression metrics, reduction percentage, developer team financial ROI savings). Distinguishes itself from the single sibling it could be confused with by naming 'estimate_token_cost' 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?

Explicit 'When to use' targeting team reports and engineering leadership, plus explicit sibling routing naming 'estimate_token_cost' with its differentiating scope (per-model single-prompt cost comparisons). Covers both when-to-use and when-to-use-something-else.

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 the full burden and does it well: it discloses the no-disk-I/O contract, idempotency, offline operation, and the supported language set. The gap is failure behavior — nothing says what happens with an unsupported extension or code the parser cannot handle, which matters for a tool taking arbitrary input plus a language hint.

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

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

Front-loaded with the core purpose in the first sentence, then labeled Behavior / Usage Guidelines / Returns sections that are easy to scan. Slightly verbose — the 80-95% figure appears twice and the language enumeration partially duplicates the schema's extension list.

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 return values need not be spelled out, yet the description still notes the Markdown fenced-block plus token-reduction percentage. Combined with the behavioral and routing detail, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents code, reduction_mode tiers, and file_path_or_ext extensions. The description's restatement of the ultra/balanced tiers and the language list adds emphasis but no meaning 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?

States a specific verb and resource ('Compresses arbitrary in-memory source code or text into compact AST/interface signatures') and pins the transform as on-the-fly/in-memory. That scope qualifier cleanly separates it from disk-scanning siblings like get_project_context_tree before the agent opens 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?

Explicit 'When to use' names the concrete scenario (compressing in-memory code blocks or clipboard buffers before LLM prompts) and 'Sibling Routing' names the two alternatives for the on-disk case. Both when-to-use and when-not-to-use 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?

With no annotations, the description carries the full burden and does so well: it declares read-only behavior, idempotency, and that it is 100% offline with no remote calls, which answers the key safety and side-effect questions. It does not cover error/fallback behavior or permission requirements, so it falls short of the top band.

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

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

Front-loaded with the core purpose and organized into Behavior, Usage Guidelines, and Returns blocks; each line carries useful information. It is somewhat long for a two-parameter read tool, which keeps it out of the top band.

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

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

Given an output schema exists, return details are optional, yet the description still summarizes the Markdown return shape. Combined with the explicit behavior and routing sections, an agent has everything needed to call 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% and both parameters (project_root, extra_guidance) are fully documented in the schema. The description only tangentially reinforces this by mentioning tzero.rules.json lookup, adding little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Retrieves) and a precise resource (active T-4 architectural tier boundary definitions, constraints, and zero-leak security rules), including the source of truth (tzero.rules.json or built-in defaults). An agent can distinguish it immediately from sibling tools like enforce_architecture_boundaries and generate_architecture_blueprint.

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

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

Explicit 'When to use' clause gives a concrete scenario (before designing features or adding imports to understand layer isolation), and 'Sibling Routing' names two alternatives with the exact 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?

With no annotations supplied, the description carries the burden and largely meets it: read-only, idempotent, and 100% offline with local regex/AST parsing. It does not disclose limits such as scan cost or behavior on very large monorepos, so it falls just short of fully comprehensive behavioral disclosure.

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 labeled Behavior and Usage Guidelines blocks, and each bullet carries information. The trailing 'Returns:' line is mildly redundant given an output schema exists, but overall it is tightly sized.

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 two-parameter read-only analysis tool with a full output schema and clear sibling routing, nothing an agent needs to select or invoke it correctly is missing. Return-format detail is correctly delegated to the 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% for both parameters, including the empty-means-whole-workspace behavior of file_path, so the baseline is 3. The description adds no syntax, path-resolution, or scoping nuance beyond what the schema already documents.

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

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

States a specific verb and resource ('Analyzes import/export dependencies, module relationships, and internal vs external package dependencies') and scopes it to polyglot source files. It is immediately distinguishable from siblings like trace_symbol_call_chain or enforce_architecture_boundaries, which it names 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 an explicit 'When to use' trigger (before refactoring, moving, or removing a module) and a 'Sibling Routing' block that names two alternatives and the exact condition that selects each (call-chain tracing vs layer-boundary enforcement). This is textbook routing guidance.

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

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

With no annotations provided, the description carries the full burden and does so: it declares read-only, idempotent/deterministic convergence, and fully offline execution, and explains the ranking semantics (inbound/outbound degree, structural criticality). This is far beyond what a bare tool name would convey.

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

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

Front-loaded one-sentence purpose, then labeled Behavior / Usage / Returns blocks. Every line carries routing or behavioral information; there is no filler.

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

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

An output schema exists, so the brief 'Returns' line is a bonus rather than a requirement. Combined with the routing guidance and behavioral notes, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100%, so top_k and project_root are already fully documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies even though nothing is missing.

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

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

States a specific verb and resource ('identifies the architectural backbone and most critical modules') and names the mechanism (PageRank centrality over AST import/reference topologies). This is unmistakably distinct from siblings like query_module_dependencies or generate_architecture_blueprint.

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

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

Explicit 'When to use' condition (exploring an unfamiliar codebase to separate core modules from peripheral utilities) plus a 'Sibling Routing' block that names two alternatives and the exact condition selecting each. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses read-only (in-memory query, no file modification), idempotent/deterministic ranking, and privacy ($0 cost, no external embedding APIs). It does not address latency or indexing cost on large workspaces, a minor gap for a search 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?

Well-structured with front-loaded purpose and clear Behavior/Usage/Returns sections with bullets. It is slightly verbose (the Returns section overlaps the output schema), but every section is scannable and earns most of 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 no annotations but an existing output schema, the description covers behavior, usage, and safety/privacy adequately. The Returns description is partly redundant with the output schema, and no latency/scale caveat is given, but an agent has enough 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 all three parameters are already documented in the schema. The description adds value only by clarifying the query is natural-language/conceptual with examples; top_k and project_root receive no added meaning beyond the schema. Baseline 3 applies.

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

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

The description states a specific verb (search) and resource (codebase) with precise scope: hybrid BM25 + TF-IDF semantic search across AST tokens, function headers, and docstrings. It clearly distinguishes itself from siblings by naming grep/ripgrep and find_dead_code as different tools.

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

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

It explicitly states when to use the tool ('conceptual natural language queries') with concrete examples, and provides explicit sibling routing: exact/regex matches go to grep/ripgrep, unused-code detection goes to find_dead_code. 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?

No annotations are provided, so the description carries the full burden, and it does so well: read-only AST traversal, deterministic/idempotent, fully offline. It stops short of noting practical limits such as cost/complexity at high max_depth on large codebases, so it is strong but not exhaustive.

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

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

Front-loaded with the core action and well-organized under Behavior/Usage/Returns headings; every bullet is relevant. The 'Returns' line slightly duplicates the output schema, which is the only small 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 read-only trace tool with full schema coverage and an output schema, the description covers purpose, behavior, routing, and result shape. Nothing an agent needs to invoke and interpret it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented. The description adds only marginal meaning by framing max_depth as the recursion limit that bounds the rendering and symbol_name as an 'exact' name; the baseline 3 applies 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+resource: 'Traces deep execution paths across the codebase AST,' then defines both traversal directions (upstream callers, downstream callees). An agent can distinguish it from siblings without opening the schema, and the sibling-routing section reinforces the distinction.

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

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

Explicit 'When to use' triggers (debugging execution flows, tracing data paths, seeing recursive calls) and explicit alternatives: 'analyze_change_impact' for blast-radius scoring, 'query_module_dependencies' for module imports. Conditions selecting each sibling are named.

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 the full burden and does well: it declares read-only ('does not modify source files'), idempotent/deterministic, and 100% offline, and it explains the return content. It stops short of only minor items like how mismatches are ordered or performance bounds.

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

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

Front-loads the core purpose, then uses labeled Behavior/Usage/Returns sections that are easy to scan. Slightly verbose in places (e.g., restating read-only and offline separately), but every line is relevant.

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 verification tool, the description covers what it checks, how (AST against local symbol catalog), the safety profile, when to run it, sibling routing, and even the return shape. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents proposed_code, target_file, and project_root. The description adds only marginal framing ('against known workspace AST signatures') and doesn't add syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Parses proposed code and verifies all internal imports and function/method call contracts') with concrete scope (argument counts, keyword parameter names, AST signatures). Clearly distinguishable from siblings like enforce_architecture_boundaries and audit_codebase_quality.

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

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

Explicit 'When to use: Run BEFORE applying AI-generated code' with the failure modes it prevents, plus an explicit sibling route ('To enforce layer boundary separation rules, use enforce_architecture_boundaries'). Both when-to-use and alternatives are named.

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 and does so well: it declares read-only behavior, idempotency/determinism, fully offline operation with zero network calls, and that detections are masked rather than exposed. It also describes the return shape (pass/fail, masked snippets, paths, line numbers), which is exactly the disclosure a mutation-free scanner needs.

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

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

Front-loaded with the core claim and organized under labeled Behavior/Usage/Returns sections, so scanning is fast. Minor redundancy in restating '100%' privacy and zero-cost claims across the opening line and the Offline bullet keeps it just short of optimal.

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 return values need no elaboration, and the description still covers scope, safety profile, determinism, and offline guarantees. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds marginal but real value by framing the three modes (single file, in-memory snippet, whole workspace) in the opening sentence. It does not, however, clarify precedence when multiple targets are supplied simultaneously.

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 (scans file/snippet/workspace for hardcoded secrets) and enumerates the exact secret classes targeted. It explicitly separates itself from the sibling 'audit_codebase_quality', so an agent can route without opening either schema.

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

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

Gives a concrete trigger ('run before git commit, push, or public release') and explicit sibling routing to 'audit_codebase_quality' for broader quality audits. Both when-to-use and when-to-use-something-else are covered.

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