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 disclose meaningful behavior: it displays a closing card, offers a 'View on GitHub' button, speaks the summary, and blocks until spoken. This is genuinely useful, though it does not disclose post-condition behavior such as whether tour state is reset or what is returned.

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 tight sentences, front-loaded with the primary purpose followed by precise behavioral detail and a blocking caveat. Zero filler; every clause earns its place, and the blocking note is correctly placed at the end where it is actionable.

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 single-parameter tool with no annotations and no output schema, the description covers the main outcomes the agent needs to know: what is shown, what is spoken, and that the call blocks. The only gap is unclear guidance on what content makes a valid summary.

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 0%, so the description must compensate for the bare schema property 'summary'. It partially does: the summary is the content that appears in the closing card and is spoken aloud. This conveys the parameter's role, but it stops short of giving format or content guidance.

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

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

The description states a specific verb and resource ('Finish the tour'), then elaborates with concrete behavior: closing summary card, 'View on GitHub' button, and spoken summary. It clearly differentiates from siblings like start_tour, show_step, and tour_status by being the terminal action of the tour lifecycle.

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?

Usage is implied by the phrase 'Finish the tour' — it is the end of the tour lifecycle, the natural counterpart to start_tour. However, the description never explicitly says when to call it versus show_overview or tour_status, nor does it state any exclusions or prerequisites, leaving selection 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 burden and does disclose the output shape (every hunk, line kinds, line numbers, text). However, it omits any behavior around errors, missing files, or side effects, though the read-only nature is implicitly clear from 'Return'.

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 compact sentences with no filler. The core output is front-loaded, followed by a practical usage tip. Every sentence adds value.

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

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

For a simple two-parameter tool with no output schema, the description adequately explains the returned structure and the intended use case. It could mention edge cases like invalid paths or empty diffs, but the essentials are present.

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

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

Schema description coverage is 0%, and the description does not explicitly define pr_url or path formats. It does add contextual meaning by tying them to 'one changed file in the PR', but leaves details like how to specify a path or URL unresolved.

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 specific verb 'Return' and the resource: the full parsed diff for one changed file in the PR, including hunk and line details. It distinguishes itself from sibling tools like show_step and get_pr_info by focusing on reading actual code changes.

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 a clear usage purpose: 'Use this to read the actual code changes so your show_step narration is accurate.' This tells the agent when to call it, though it does not explicitly name alternatives or when not to use it.

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 explains what is returned (metadata, compact per-file summary, diff hunk ranges) and how the output maps to show_step's line parameters. It does not discuss auth or error edge cases, but for a read-only fetch tool it gives substantial behavioral context without contradicting anything.

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 with the core purpose, then provides integration instructions and a pointer to get_file_diff. Every sentence earns its place; there is 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?

Given no output schema or annotations, the description adequately explains what the tool returns and how to consume those results with show_step and get_file_diff. It could add URL format details and error behavior, but it is largely complete for its role in the tour workflow.

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 only parameter, pr_url, has no schema description (0% coverage), and the description does not compensate by explaining accepted URL formats or examples. The parameter name is suggestive, but no actual semantic guidance is added beyond the structural schema.

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

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

The description states a specific verb and resource: fetching a GitHub pull request's metadata and a compact summary of every changed file. It clearly differentiates itself from siblings like get_file_diff and show_step by positioning itself as the initial information-gathering step.

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 sequencing is provided: 'Call this FIRST, before start_tour' and 'Use get_file_diff to read the actual changed lines of a specific file.' This tells an agent exactly when to invoke this tool and which 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 for behavioral disclosure. It usefully discloses that the tool 'Blocks until the narration finishes speaking' and that it presents a visual card with a spoken caption. However, it does not mention side effects (e.g., whether it modifies state, requires a selected PR, works independently of a tour, or returns a value), leaving agent-relevant behavior under-specified.

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

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

The description is front-loaded with the intent, includes the blocking trait, and adds a concrete usage constraint in three sentences. No redundant content or filler; every sentence contributes to understanding or using the 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 2-parameter tool with no output schema and no annotations, the description covers the core behavior and parameter constraints. But it leaves out contextual prerequisites and interactions with sibling tour tools: whether an active PR must be loaded, whether this is a tour step, or whether it requires an active tour context. Since the sibling list suggests a tour workflow, this information is useful for correct invocation.

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

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

The schema description coverage is 0%, so the description must compensate. It does so by adding meaning to both parameters: 'narration' is explained as a spoken caption, with a length constraint ('1-3 short, plain-language sentences'), and 'key_points' is clarified as 'optional short bullet' content, suggesting a visual bulleted list beyond the raw schema's 'array of strings'.

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

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

The description states a specific action and resource: 'Show the PR overview card' with the exact fields ('title, author, +/- stats, file count'). It clearly differentiates from siblings like get_pr_info (which retrieves data) and show_step (which shows tour steps) by emphasizing the narrated spoken caption and blocking behavior.

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 guidance on when to use this tool vs the sibling tools. It doesn't mention when to choose show_overview over get_pr_info or show_step, and no exclusions or preconditions are provided. The only usage constraint ('Keep narration to 1-3 short, plain-language sentences') concerns content format, not 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, the description carries full burden and it does so excellently. It discloses all behavioral traits: selecting in the file tree, animating diff, scrolling, pulsing/dimming, displaying and speaking narration, blocking until speech ends, snapping out-of-range lines to the nearest hunk, and reporting warnings. This is comprehensive and contradicts nothing.

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 dense but every sentence adds value. It front-loads the core action, then layers behavioral details (blocking, sequential), optional parameter behavior, and edge cases. No fluff or repetition; it is efficiently 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?

For a 6-parameter tool with no annotations and no output schema, the description covers the action, parameter semantics, edge cases (snapping, warnings), and usage constraints (blocking, sequential). It does not explicitly mention prerequisites like an active tour or the return value, but these are implied by the tour context and the mention of warnings, making it sufficiently complete for correct invocation.

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

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

Schema coverage is 0%, so the description must explain each parameter, and it does: file (selects in tree), side (line numbers on that version), style (highlight vs spotlight), line_start/line_end (scroll range, omit for whole file, out-of-range snapping), narration (caption + speech). This fully compensates for the lack of schema descriptions.

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

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

The description states a specific verb ('show') and resource ('one tour step'), then details the exact sequence of actions: selecting a file, animating its diff, scrolling to a line range, and applying a highlight or spotlight. It clearly distinguishes itself from siblings like start_tour, show_overview, and end_tour by describing the step-level behavior within a tour.

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 clear usage context: call sequentially to pace the tour because the call blocks until speech completes, and omit line_start/line_end to frame the whole file. It does not explicitly contrast with alternatives, but the context of being a step in a tour and the mention of blocking sequential behavior imply when it should 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, the description carries full behavioral burden and succeeds: it discloses side effects (opens viewer in browser, replaces previous tour, enables audio on Start), a blocking condition (~30s wait for user), and the fetch step. This is unusually transparent.

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 dense sentences with no filler. Each clause carries operational information: fetch, open viewer, block, replace, and prerequisite call.

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 tool with no annotations, the description covers side effects, blocking behavior, and sequencing. It doesn't describe return values, errors, or what happens after Start, but those are likely secondary for an agent deciding whether and when to call 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 schema only gives parameter names/types, so the description must add meaning. pr_url is implied by 'Fetches the PR,' and tour_title is loosely tied to 'shows a title/start screen,' but the description never explicitly maps tour_title to the displayed title. Coverage is adequate but not explicit.

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: 'Start an animated tour of the pull request.' It then details the concrete workflow (fetch PR, open viewer, show start screen), clearly distinguishing it from sibling tools like show_overview or get_pr_info.

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 context: 'Call get_pr_info first so you can plan your steps.' This is a clear prerequisite and sequencing instruction, though it does not enumerate exclusions or alternative tools.

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 of behavioral disclosure. It does well: 'Diagnostics' signals a read-only nature, and it enumerates the state it reports (active, connected, audio, steps, URL). It does not explicitly state it has no side effects, but the diagnostic framing implies non-mutation, which is sufficient for a 0-parameter status 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?

Two sentences with zero filler. The diagnostic purpose and output fields are front-loaded, followed by a single targeted usage condition. Every word earns its place, and the structure makes it scannable for an agent.

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 no output schema, the description must convey what the tool returns, and it does: active state, browser connection, audio state, steps shown, and viewer URL. For a 0-parameter diagnostics tool, this covers the essential information an agent needs. It could mention that the viewer URL is only present when connected, but this is a minor omission.

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 tool has 0 parameters with 100% schema coverage, so there is nothing for the description to clarify about arguments. The description instead clarifies what the tool returns (the diagnostic fields), which is the relevant semantic content. Baseline 4 applies for a parameterless tool.

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 'Diagnostics:' and specifies exactly what is reported: tour active state, browser viewer connection, audio state, steps shown, and viewer URL. This clearly distinguishes it from the action-oriented siblings (start_tour, show_step, end_tour), making its purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Use this if a call timed out or you suspect the viewer window was closed.' This is concrete and actionable. It stops short of naming explicit alternatives or exclusions, but the diagnostic framing makes it obvious this is the status-check tool among action tools.

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