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

The description discloses that the tool returns per-file token costs, strategies, and which files to drop, which is useful behavioral information. However, since no annotations are provided, the description carries the full burden and does not explicitly state whether the tool performs read-only analysis or has side effects. It also doesn't mention any permissions or rate limits.

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

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

The description is two sentences, front-loaded with the core purpose and usage guidance. Every clause adds value; 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?

The description covers the main purpose, usage timing, and return values, which is important since there is no output schema. It lacks details on the compression strategies or how token costs are computed, but it is sufficient for an agent to know when to invoke this tool.

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

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

The input schema already provides descriptions for files, max_tokens, and task (75% coverage), and the description adds context about the tool's planning purpose. It doesn't elaborate on the repo parameter or provide additional parameter semantics beyond what the schema offers.

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

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

The description clearly states the tool's function: planning how to fit files under a token budget and selecting compression strategies per file. It mentions specific outputs (per-file token costs, strategies, and files to drop), and the verb 'Plan' distinguishes it from sibling tools like redcon_compress that likely execute compression.

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

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

The description explicitly says 'Use before reading several files at once', providing a clear usage scenario. It doesn't name alternative tools but implies when to use it relative to reading files. It could be improved by mentioning what not to use it for.

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

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

With no annotations, the description carries the transparency burden. It discloses the tool's behavior: produces a compressed view, reduces tokens 3-10x, includes specific content, and may be insufficient compared to full file. This is useful but doesn't cover error conditions or exact output structure.

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

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

The description is two sentences with no waste. The first sentence states the purpose and key characteristics; the second gives clear usage guidance. It is appropriately front-loaded.

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

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

The description is sufficiently complete for a simple read/compress tool. It explains what the tool does, what the output includes, and when to use it. The lack of output schema is mitigated by describing the content types. It doesn't explain the exact return format, but that's not critical for selection/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 75% (3 of 4 params described). The description adds the concept of 'task-scoped' to clarify the task parameter's role and mentions token reduction related to max_tokens. However, it doesn't meaningfully expand on path or repo beyond the schema.

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

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

The description clearly states the tool generates a 'task-scoped compressed view of one file' with a specific content set (signatures, imports, relevant sections) and token reduction. However, it does not explicitly name sibling tools for differentiation, so it's clear but not maximally distinguishing.

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

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

The description gives explicit usage guidance: 'Prefer this over reading a whole file; fetch the full file only if it is insufficient.' This clearly states when to use this tool versus the alternative of reading the full file, though it doesn't address when to choose other redcon siblings.

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 burden. It discloses key behavioral traits: lightweight nature, cost (a few hundred tokens), and task-based filtering. It does not explicitly state whether the operation is read-only, but the 'map' phrasing implies a safe read operation. This is good value beyond the schema.

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

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

Two sentences, front-loaded with the core purpose, and every phrase earns its place. No filler or repetition.

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

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

For a simple overview tool with no output schema, the description covers what it does, when to use it, cost, and alternatives. It does not describe the output format in detail, but the concept of a 'map' is straightforward. It is sufficiently complete for an agent to make a confident selection decision.

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 50%; only 'task' is described in the schema. The description itself doesn't detail parameters but does tie 'task' to module filtering. The 'repo' parameter lacks any description but has a default value, reducing ambiguity. The description adds marginal value, but not enough to fully compensate for the gap.

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

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

The description clearly states the tool produces a lightweight repository map grouped by directory and filtered to the task's modules. It explicitly differentiates from the sibling tool redcon_repo_map by noting that one should use that tool for signatures.

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 usage guidance: 'Use to orient instead of ls -R or find' and 'For signatures, use redcon_repo_map.' This tells the agent exactly when to invoke this tool and what alternative to choose for a different need.

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

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

With no annotations provided, the description carries the full burden. It discloses that a shell command is executed and output is verified, but it omits safety implications, expected output format, or how the verification works. The disclosure is moderate but not rich.

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

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

Two sentences with no filler. The core behavior and usage alternative are front-loaded, making it concise and well-structured.

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 7 parameters, no output schema, and no annotations, the description is underspecified. It lacks parameter details, return format, constraints, and environment assumptions. This is minimal for a complex execution 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 0%, and the description does not explain any of the 7 parameters (command, cwd, quality_floor, timeout_seconds, etc.). The mention of compression is vague and does not map to any parameter.

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 clear action sequence: run a shell command, compress its output, and verify against the M8 quality harness. It also distinguishes itself from sibling redcon_run by specifying when to use it for a structured pass/fail verdict.

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

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

Explicitly says to use instead of redcon_run when a structured pass/fail verdict is needed, providing a direct alternative and use context. This gives clear guidance on tool selection.

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

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

With no annotations provided, the description carries the full burden. It does disclose the key output ('top-K paths with scores and reasons') and its workflow role, but it doesn't explicitly state whether the operation is read-only, whether it has side effects, or any cost/performance implications. This is adequate but not rich.

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

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

The description is two sentences, front-loaded with purpose and usage, and contains no filler. Every phrase serves a purpose: it explains what the tool does, when to call it, what it returns, and what to do next.

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 relatively simple tool with three parameters, no output schema, and no annotations, the description covers the essential context: purpose, invocation order, return content, and next step. It could further elaborate on output format or edge cases, but the description is sufficient for selection and 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?

The input schema already has 100% coverage with descriptions for repo, task, and top_k. The description only adds 'top-K' without providing any additional parameter syntax, defaults, or nuances beyond the schema, so the baseline score of 3 applies.

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

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

The description opens with a specific verb and resource: 'Rank repository files by relevance to a task.' It clearly differentiates from siblings by positioning itself as the first step—'Call this FIRST'—and by referencing a follow-up tool, redcon_compress, while implicitly distinguishing from grep/reading actions.

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: 'Call this FIRST on a new task, before grepping or reading' and provides a clear follow-up instruction. The guidance is strong on timing and context, but it doesn't explicitly list situations where an alternative sibling should be preferred beyond the grep/reading contrast.

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

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

With no annotations, the description carries the full burden and does disclose key behavior: the output is token-budgeted and it degrades to a path-only listing without the redcon[symbols] extra. This gives the agent clear expectations, though it does not explicitly state that the operation is read-only, which is implied.

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

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

The description is three concise sentences that lead with the tool's purpose, then cover usage and degradation behavior. There is no redundant or filler content.

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

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

The description covers the core output and usage context, but the required 'task' parameter is undefined, and the ranking criteria for 'top ranked' are opaque. With no output schema or annotations, the agent still faces ambiguity about the expected input and details of the result.

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

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

Schema description coverage is 0%, so the description must compensate. It indirectly explains 'budget' via 'token budget' and 'top_files' via 'top ranked files', but the required 'task' parameter is left entirely unexplained, leaving a significant gap for correct invocation.

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

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

The description clearly states that the tool generates a repo map with top-ranked files, class/function signatures, and line numbers under a token budget. The phrase 'Use for code structure across many files at once' distinguishes it from sibling tools by specifying its broad scope.

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 provides an explicit usage context: 'Use for code structure across many files at once.' This tells the agent when to select this tool, though it does not mention specific alternatives or circumstances where it should not be used.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses compression behavior, hard token caps, failure detail preservation, and the default-disabled status. However, it does not explicitly warn about potential side effects of arbitrary command execution (e.g., file modifications, network access), which is a notable omission for a command runner.

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

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

The description is compact and front-loaded, starting with the core action and purpose. Each of the three sentences adds valuable information: what the tool does, when to use it, and a critical configuration note. No words are wasted.

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

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

Given the tool's complexity (8 parameters, no output schema, no annotations), the description provides a solid overview with purpose, usage criteria, and enablement. It does not fully describe the return format or handling of edge cases, but the high schema coverage compensates for missing parameter details. A brief caution about command side effects would improve completeness.

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

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

The input schema provides 100% coverage for all parameters with detailed descriptions, so the baseline is 3. The tool description adds little beyond the schema; it mentions compression and token caps but does not elaborate on parameters like quality_floor or semantic_fallback. No additional semantics are provided.

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

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

The description clearly states the tool's function: 'Run a shell command and return its output compressed for LLM consumption,' naming specific use cases (pytest, git, builds, coverage). It distinguishes the tool from siblings that perform static repository analysis by emphasizing command execution and output compression.

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

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

The description explicitly says 'Use instead of a raw shell when output may exceed a screenful,' giving a clear condition for when to choose this tool. It also notes the critical prerequisite 'DISABLED by default; set REDCON_MCP_ENABLE_RUN=1 to enable,' which is essential for correct invocation.

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

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

With no annotations, the description carries the full burden. It discloses key behavior: scope='ranked' limits matches to task-relevant files, and scope='all' covers the whole repo. However, it does not explicitly state that it is read-only, what the output format is, or any other side effects, leaving some ambiguity.

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

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

The description is two sentences, front-loaded with the primary purpose, and every sentence provides useful information without redundancy or filler.

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

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

For a search tool with no output schema, the description covers the core functionality, scope behavior, and usage preference. It omits details on return format and the remaining parameters, but these are not critical for basic invocation. Overall, it is reasonably complete for a low-risk read-only operation.

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

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

Schema description coverage is low (33%). The description adds meaning to the 'scope' parameter by explaining the two enum values and clarifies that 'task' is used for ranked scope. It does not explain 'repo', 'top_k', or 'max_results', which remain undocumented, so compensation is incomplete.

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

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

The description clearly identifies the tool as a regex search with a specific resource (codebase) and differentiates it from raw grep. However, it does not explicitly distinguish it from sibling search tools like redcon_structural_search, which is a minor gap.

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 a clear when-to-use: 'Prefer over raw grep on large repositories.' It also explains the scope parameter choices (ranked vs all), giving context for typical usage. It does not mention exclusions or alternative sibling tools, but the guidance is sufficient for basic use.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses a critical dependency (ast-grep availability) and the resulting fallback behavior ('returns backend=unavailable'), which is valuable transparency. It also implies read-only semantics via 'Search', but does not explicitly mention side effects or other behavioral traits like rate limits. Still, key behavior is disclosed.

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

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

The description is two sentences, front-loaded with the primary action, and every phrase adds value: AST pattern, difference from regex, behavioral consequences, dependency, and fallback. No wasted words.

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

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

Given that this is a search tool with a dependency and fallback, the description covers the essentials: what it does, how it differs, prerequisites, and failure behavior. There is no output schema, so return format is not described, but given the context of a search operation and sibling tools, the description is sufficient for correct selection and 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 coverage is only 25% (only 'language' has a description). The description adds crucial meaning to 'pattern' by explaining it is an AST pattern (not regex), which is essential for correct usage. However, 'scope', 'max_results', and 'language' are not elaborated, and the low schema coverage means the description should do more to compensate for those parameters.

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

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

The description clearly states the tool searches by AST pattern ('Search by AST pattern'), differentiates from regex-based search ('not regex'), and specifies a key behavioral consequence ('matches skip comments and strings'). This distinguishes it from sibling redcon_search.

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

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

The description explicitly contrasts with regex search, implies when to use it (when AST-aware matching is needed), and provides a clear fallback mechanism ('callers fall back to redcon_search') plus a prerequisite ('Needs ast-grep on PATH or redcon[ast_grep]'). This gives strong guidance on when and how to use the tool.

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