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

No annotations are provided, so the description carries the burden of behavioral disclosure. It covers the key edge case by stating it 'returns an empty selection object when nothing is highlighted' and names the return fields. It does not explicitly say the tool has no side effects or describe error behavior, but for a simple getter this is adequate.

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 sentences with the core action first, then user-facing trigger phrases, then the empty-selection edge case. Each sentence adds distinct value, and there is no fluff or 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?

With no annotations and no output schema, the description supplies the essential return shape (file path, line range, selected text), the empty case, and clear guidance on when to call it. For a zero-parameter, low-complexity tool, this is complete enough for an agent to invoke and interpret results.

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 has zero parameters, giving this dimension a baseline of 4. The description correctly focuses on output and usage rather than parameters, and there is no parameter information left undocumented.

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 ('Get'), a precise resource ('the code the user has selected or highlighted in VS Code'), and the return payload (file path, line range, selected text). It also positions itself relative to walkthrough/show_code as a prerequisite step, making the tool's function clear even alongside siblings.

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 trigger phrases ('this code', 'what I've selected', 'the highlighted block') and a workflow rule ('before calling walkthrough/show_code when the user has already selected the code'). It does not explicitly state when not to use the tool or list alternative conditions, so it falls just short of full 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly states the tool both reads and mutates settings, and it adds that 'Changes persist across sessions,' which is valuable side-effect information. It could go further by describing whether omitted parameters are preserved, but it is transparent about the core read/write 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?

The description is three focused sentences with the primary action front-loaded. Every clause adds useful information: scope, triggering user intents, the sibling exclusion, the no-argument read behavior, and persistence. There is no repetition of schema details 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 simple settings tool with four optional parameters, the description covers purpose, usage, parameter intent, and persistence, and it routes the one overlapping case to the correct sibling. There is no output schema and no mention of the return shape, but an agent can reasonably infer that a read call returns current settings; the remaining ambiguity is minor.

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

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

Schema coverage is 100%, so the schema already documents each parameter clearly. The description adds value by mapping user-facing concepts (muting narration, toggling bubbles, autoplay delay) to the settings and by clarifying that invoking with no arguments is a read operation, which the schema alone does not express.

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: 'View or update global walkthrough settings' and explicitly enumerates the settings involved. It also distinguishes itself from the sibling walkthrough_voice_selection by saying exactly what it is not for, so an agent can select it correctly.

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 when-to-use guidance ('Use when the user asks to enable, disable, or configure any of those'), an explicit exclusion ('Do NOT use to change the narration voice name'), and names the alternative tool to use instead. It also states that calling with no arguments reads current settings, giving clear decision rules.

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 of behavioral disclosure. It clearly states the core behavior: opening a file, highlighting specific lines, and suppressing explanation bubbles. It also discloses the coordinate conventions. It doesn't mention edge cases like missing files or return behavior, but for a read-only editor-open action the disclosed behavior is sufficient.

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: the core behavior appears in the first sentence, followed by usage rules, explicit don'ts, and coordinate semantics. Every sentence earns its place and none are redundant with the schema or annotations.

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 five parameters, no output schema, and sibling tools that could be confused with it, the description is complete. It explains when to use it, when not to use it, what behavior to expect, and how to interpret the coordinate parameters. There is no significant missing information an agent would need 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 baseline is 3. The description adds meaningful value beyond the schema by specifying that line numbers are 1-based and character offsets are 0-based. This clarifies the relationship between start/end lines and start/end chars, which is essential 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 states a specific verb and resource: 'Open a file in VS Code and highlight specific lines.' It clearly differentiates itself from the walkthrough sibling by noting it performs the action 'without any explanation bubble.' An agent can immediately understand what this tool does and how it differs from related 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?

The description gives explicit when-to-use guidance: 'Use when the user asks to show, open, jump to, or point at specific code with no commentary needed.' It also provides clear exclusions: use walkthrough for explanations and multi-step tours. This leaves no ambiguity about selecting this tool versus 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?

With no annotations, the description carries the full behavioral burden and delivers: arg-dispatch side effects (single-step explain vs highlight-only vs narrated tour vs clear vs navigation), the teleprompter UX dependency on the highlights[] pattern, and the TTS quirk where numbered lists are read as 'one dot… two dot'. It also discloses formatting constraints (real newlines not literal backslash-n, avoid ## headers, use **bold**) and coupling to global voice/bubble/autoplay settings — all beyond what structured fields could express.

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?

Long, but every sentence earns its place — the density reflects six behavioral modes plus critical formatting rules. Front-loaded with purpose, triggers, and the exclusion before diving into dispatch details; the sectioned guidance (multi-point steps, TTS no-numbered-lists, markdown rules) is compact and directly actionable with zero 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 tool this complex — three params, six action modes, a nested highlights structure, no output schema, no annotations — nothing needed for correct invocation is missing: entry conditions, exclusions, formatting rules, settings coupling, and status-on-no-args are all present. The only minor gap, explicit return-format details beyond the no-args status, is low-risk since the tool's effects are primarily visual/audible UI state.

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% with unusually detailed per-property descriptions, so baseline is 3. The description adds meaning by synthesizing parameters into a behavior matrix (one step with explanation = explain; one without = highlight; multiple = tour) and by prescribing usage patterns ('keep explanation to 1–2 intro sentences… put each point in its own highlights[] entry'). It supplements `step` with 'pass step index for goto' and maps the full action enum to behaviors, though the schema already documents individual properties.

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?

Opens with a specific verb+resource+scope ('Show, explain, and tour code in VS Code') and frames itself as the one tool for code presentation with commentary. Explicitly names its sibling as the alternative for commentary-free jumps: 'Do NOT use for jumping to code without commentary — use show_code instead.' An agent can distinguish it from show_code without opening the schema.

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

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

Lists concrete trigger phrases ('explain code, walk through code, tour a codebase, ask how does this work, navigate an active tour, clear bubbles, or check walkthrough state') so an agent knows exactly when to fire it. Provides an explicit exclusion and names the sibling alternative (show_code). The dispatch matrix further tells the agent which argument shape to choose per intent.

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 behavioral burden. It discloses that passing `voice` switches to a specific voice and plays a sample, `list: true` avoids playing audio, `audition: true` plays voices back-to-back, and that voice selection persists across sessions. It does not mention side effects like requiring an active walkthrough or network usage, but covers the main state-changing and persistence behaviors well.

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 appropriately sized and front-loaded with the core actions, then the usage triggers and exclusions, then parameter guidance. Every sentence carries useful signal without redundancy or irrelevant detail. The structure flows from high-level purpose to specific parameter behavior.

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 5 parameters and no output schema, the description covers the key decision points: what each parameter does, when to use the tool, and a critical exclusion (toggle vs. settings). The only minor gap is not describing the shape of the response (e.g., what the list output contains), but the parameter list and examples make it largely inferable.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by linking parameters to high-level intents (e.g., 'Pass `list: true` to list voices without playing audio') and by giving examples of locale prefixes and voice names. It reinforces and clarifies, though it does not introduce entirely new parameter 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?

The description clearly states the specific operations: change the narration voice, preview it, list available voices, and audition voices back-to-back. It names the resource (narration voice) and distinct actions. It also differentiates from the settings tool by explicitly saying 'Do NOT use to toggle voice on/off'.

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 provides explicit usage conditions: use when the user asks to change the voice, try a different voice, hear voice options, compare voices, or asks 'what voices are available'. It also states a clear exclusion (use settings tool for toggling) and explains when to pass `voice`, `list: true`, `audition: true`, `locale`, and `gender`. This is outstanding guidance for an agent.

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