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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds a genuine behavioral trait beyond that: the extraction is 'deterministic' and uses 'no LLM', telling the agent results are stable and reproducible. It doesn't discuss rate limits or failure modes, but the determinism claim is real added value.

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

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

A single front-loaded sentence that leads with the verb and the determinism guarantee, then enumerates outputs. The enumeration is long but each item is informative and non-redundant; only the parenthetical nesting makes it slightly dense.

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 explanation, yet the description helpfully names the signal categories anyway. Combined with annotations covering the safety profile and 100% schema coverage, an agent has everything needed to invoke it correctly, though nothing is said about behavior on invalid issue numbers or missing repos.

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 owner, repo, and issue_number are already fully documented in the schema, including the origin-remote fallback behavior. The description adds no parameter-level syntax or format guidance, so the 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 and resource ('extract triage signals from an issue') and enumerates the exact outputs (type guess, error messages, stack frames, file paths, code blocks, suggested queries). The parenthetical '(no LLM)' plus the enumerated artifacts make it impossible to confuse with get_issue or get_docs.

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 clearly signals the workflow context by noting the suggested queries are meant 'to pass to search_codebase', giving the agent a downstream routing cue. It stops short of stating when NOT to use it (e.g., vs. get_issue for raw issue body retrieval), so it is clear context without explicit exclusions.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed world), so the bar is lower. The description nonetheless adds real behavioral detail: the fallback behavior when no arguments are supplied, the ranked-by-keyword-hits selection, and the fixed cap of 3 sections for topic-only calls. It doesn't discuss truncation interplay with max_chars in any depth, which is the only notable gap.

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

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

Three tight sentences, front-loaded with the resource scope, then the three invocation modes in a predictable path/topic/neither progression. Every clause carries a distinct constraint; nothing is 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 return-value documentation is not required, yet the description still specifies what each mode yields. With 4 optional parameters, zero required, and full schema coverage, an agent has everything needed to call it correctly in any mode.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the per-field schema text by explaining the interaction semantics: path alone returns the file or just the heading-matched section when topic is also present, and topic alone switches to ranked multi-section retrieval. That combinatorial meaning is not derivable from the schema fields individually.

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 (read project documentation) and enumerates the exact file patterns covered (README*, CONTRIBUTING*, root *.md, docs/**/*.md), which is unusually precise. It does not, however, explicitly contrast itself with the sibling search_codebase, so the boundary between doc reading and code search is left to inference.

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 mode-selection rules: path+provision to fetch a file or matching section, topic only to get the 3 best keyword-ranked sections, neither to get the README intro plus docs list. That is clear operational guidance for invoking the tool. It stops short of naming when a sibling (e.g. search_codebase) would be preferable.

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=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description repeats 'Read-only' and lists returned content, but adds no behavioral context such as auth needs, rate limits, or failure modes.

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 short sentences, front-loaded with the action and resource, followed by scope and usage cue. No wasted wording.

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

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

With rich annotations, 100% schema description coverage, and an output schema present, the description supplies enough context for correct invocation. It does not need to explain return values further.

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 four parameters are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, making 3 the correct baseline.

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

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

States a specific verb and resource: fetch a GitHub issue with its discussion. It also lists the returned fields and positions the tool as the starting point for triage, distinguishing it from sibling analyze_issue.

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 'Start here when triaging an issue,' giving clear usage context. It does not name when not to use it or explicitly route to alternatives like analyze_issue, so it stops short of a 5.

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=false, openWorldHint=false, idempotentHint=false, and destructiveHint=false. The description adds valuable context beyond annotations: it auto-detects vitest/jest/pytest/npm test, notes that remote mode runs only a fixed configured command, and returns pass/fail counts plus a run_id. It does not contradict any annotation.

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

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

The description is a single, front-loaded sentence that covers purpose, auto-detection, remote-mode behavior, and return-value routing without waste. Every clause earns its place.

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

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

For a test-running tool with an output schema and annotations, the description supplies the missing operational context: what gets auto-detected, how remote mode differs, and what the run_id is for. Nothing an agent needs to call or use the tool 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 both 'repo' and 'filter' thoroughly. The description does not add parameter-level semantics beyond what the schema provides, which matches the baseline 3 for high-coverage schemas.

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: 'Run the project's test suite', and names the auto-detected frameworks. It also distinguishes itself from the sibling summarize_test_failures by explaining the run_id handoff, so an agent can tell the tools apart 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 clear workflow guidance: use run_tests to execute the suite, then pass the returned run_id to summarize_test_failures for grouped failures. It does not explicitly state when not to use this tool or contrast it with other siblings like search_codebase, but the primary usage context is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral detail: .gitignore is respected and node_modules, dist, lockfiles and binaries are skipped, plus the shape of the return (matching lines with surrounding context, workspace-relative paths). It does not mention the remote-vs-local mode distinction or any result truncation behavior.

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

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

Two sentences, zero filler, with the core action front-loaded before the exclusion rules and return shape. Every clause carries 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?

An output schema exists, so return values need not be explained, and annotations plus a fully covered schema leave few gaps. What is missing is the local-vs-remote execution mode implied by the repo parameter and any note on result capping, but the description is otherwise sufficient 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%, so all six parameters are already documented in the schema, including the literal-vs-regex behavior and the repo allowlist rule. The description adds no parameter-level meaning beyond that, 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 ("Search the workspace") and immediately qualifies the mechanism (ripgrep) and scope. An agent can tell this is a full-text code search, clearly distinct from siblings like get_docs, run_tests, or analyze_issue.

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 no explicit when-to-use, when-not-to-use, or named alternative. The description says what it searches but never routes the agent away from get_docs or get_issue when those would be better. Usage is only implied by the word "workspace".

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=true, idempotentHint=true and destructiveHint=false (and closed-world), so safety is covered. The description adds interpretive context absent from the schema, notably that likely_source_files are non-test files from the stack 'where the fix probably goes' and that failures are grouped by normalized error, largest first — ordering behavior the structured fields do not 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?

A single dense sentence, front-loaded with the verb and the source of the input, followed by the contents. It is long but every clause carries new information; the parenthetical is slightly heavy but earns its place by explaining field meaning.

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

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

With a full output schema present, the description need not enumerate return values in detail, and annotations cover the safety profile. Combined, an agent has everything needed to select and call this tool on a valid run_id.

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?

There is a single parameter at 100% schema description coverage, with the pattern and origin (run_id returned by run_tests) documented in the schema itself. The description adds only the implicit linkage that the run_id comes from a prior run_tests call, so the baseline 3 is appropriate.

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

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

The description gives a specific verb (summarize) and resource (failures of a previous run_tests call), and it enumerates the returned artifacts (failing test, message, top project stack frames, likely_source_files, error groups). It is clearly distinguishable from get_issue, analyze_issue, search_codebase and run_tests.

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 anchors usage to a prerequisite — this operates on the output of a previous run_tests call — so an agent knows it must run tests first. There is no explicit when-not-use or named alternative, which keeps it short of a 5.

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