tourwright

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

Beyond the readOnly/openWorld/idempotent annotations, it explains what is returned for failures, that new targets are inferred when possible, and that YAML text input yields a `fixed` version preserving comments. This adds substantial behavioral context.

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, dense, and free of filler. Each sentence adds purpose, return behavior, or usage guidance.

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 does a good job explaining failure output and the `fixed` field. It does not fully specify the success case or complete response shape, but it is sufficient for a check 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 coverage is 100%, so the baseline is 3. The description adds meaningful input-dependent behavior: when the script is provided as YAML text, the response includes a repaired `fixed` text field.

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: run a script quickly against the real site without voice or video, and return failed steps plus proposed target fixes. It clearly distinguishes this check behavior from render/validate follow-up 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 gives a clear usage context: use after the site changed, then validate and render. It implies the alternative to full render by saying no voice or video, but does not explicitly state 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?

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the agent knows this is a side-effect-free read. The description adds that the payload is documentation content (format, actions, voices, examples) but says nothing about size, structure, or whether it returns one document or sections — modest added value against the already-covered safety profile.

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 sentence with the content summary front-loaded and the call-to-action at the end; nothing is redundant. The middle list ('every action, voices and examples') is slightly compressed and would read better as a clearer enumeration, but no filler is present.

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 parameters, no output schema and no nested structures, the description carries most of the burden and does state what content comes back. It stops short of describing the document's shape or length, which would help an agent budget reading it, but 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?

Zero parameters, so the baseline applies; there is no input semantics left for the description to carry. The one sentence is consistent with an argument-free fetch.

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 the resource plainly: the Tourwright script format, covering browser walkthroughs, narrated slides, actions, voices and examples. An agent can tell this is a reference/guide fetch rather than an action tool, though it does not state a verb and overlaps thematically with the sibling tourwright_voices, leaving mild ambiguity about which one to open for voice details.

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?

'Read it before writing a script' gives an explicit precondition that selects this tool over the action siblings (validate, render, job). It does not name any exclusions or point to the follow-on siblings such as tourwright_validate for the step after reading, so guidance is clear but not complete.

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, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds that the result appears only once done, which is useful, but says nothing about what status values exist, terminal states, or whether results expire.

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 with no wasted words. It is efficient, though the parenthetical carries meaning that could be stated more directly.

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?

There is no output schema, so the description is the only source of return-shape information; it names the three returned aspects but not their form or the terminal conditions. For a polling tool this leaves the agent to infer how to decide when to stop.

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 the id parameter is already explained as coming from tourwright_render with wait=false. The description adds no further meaning about the identifier, 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?

The description names a specific resource (a render job) and the three things it returns: status, progress, and result. That is enough to tell it apart from tourwright_render, which starts a job, but the description never names that sibling 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?

The parenthetical '(when done)' implies this is a polling tool, yet the description never says to call it repeatedly until the job completes, nor points to tourwright_render with wait=true as the blocking alternative. The relevant context exists only in the schema's parameter text, not in the description itself.

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=true and idempotentHint=false, so the mutating/non-idempotent nature is covered. The description adds real value beyond that: it discloses the blocking semantics, the exact contents of a successful return (links, local paths, duration, chapters, captions), and the asynchronous escape hatch. It does not say whether repeated calls create duplicate jobs or whether rendering consumes credits, which would have earned 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?

Two compact sentences with no filler, and the primary action is front-loaded ahead of the conditional behavior. The branching (wait=true vs otherwise) is expressed in a single parallel clause, which is easy for an agent to parse.

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 six-parameter tool with a nested options object and no output schema, the description covers the two things an agent most needs: what the call returns and how to handle the async case. The schema itself points to tourwright_guide for the script format. Minor gaps remain around failure modes and job duplication, but nothing essential for a correct invocation 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 every parameter, including wait, waitSeconds, vars, assets and options. The description only restates the wait behavior and the return payload, adding no syntax or format detail beyond the structured fields. Baseline 3 is appropriate 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?

The first sentence states a specific verb and resource: 'Queue a script for rendering.' The second sentence explains what the call produces and explicitly names tourwright_job as the polling sibling, so an agent can distinguish it from tourwright_validate, tourwright_check and tourwright_voices 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?

The description clearly explains the default wait=true flow versus the fire-and-forget flow that returns a job id for tourwright_job, which is the key decision an agent must make. It stops short of stating when NOT to use the tool (for example, running tourwright_validate first) or which sibling to pick for related tasks, so it is clear context rather than full 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?

Annotations already establish readOnly, idempotent, and closed-world behavior, so the description only needs to add context. It does so usefully by disclosing the return shape ({ ok } or a list of errors), which is not covered by any output schema. It still doesn't say how deep validation goes or what kinds of errors are caught.

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 core action and followed by the return contract. No filler, though "the list of errors to fix" is slightly loose phrasing for a return 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 small two-parameter read-only tool with no output schema, the description covers what it does and what it returns, which is most of what an agent needs. The notable gap is the relationship to the adjacent tourwright_check and tourwright_guide tools, which is left unaddressed.

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%, including the note that variables make a different video per value set and the instruction to read tourwright_guide first, so the schema carries parameter meaning. The description adds nothing about `script` or `vars` beyond what the schema already states.

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?

"Check a script without rendering it" gives a specific verb (check) and resource (script), and explicitly contrasts with rendering, which separates it from tourwright_render. However, it does not distinguish itself from the sibling tourwright_check, which an agent could plausibly confuse it with.

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 phrase "without rendering it" implies the intended pre-render validation step, but there is no explicit statement of when to pick this over tourwright_check or tourwright_guide, nor any mention of prerequisites. Usage is only implied.

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, idempotentHint, and a closed-world scope, so the safety profile is covered structurally. The description adds that results include which engines work, hinting at the returned data, but it says nothing about how voices are identified or how the engine/voice relationship is expressed — information an agent needs to actually use the output.

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 resource being listed, with no filler. The phrasing 'and which engines work' is slightly compressed and could be clearer, but nothing is 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?

The description needn't explain return shape in detail given the tool's simplicity, but it does flag the two things returned (voices and working engines) and adds the selection rule that motivates calling it. Nothing essential to invoking a zero-argument lister 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The absence of arguments is consistent with the description's framing of a plain enumeration call.

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 the resource specifically (text-to-speech voices on the server) plus a secondary payload (engine compatibility), which is more than the title 'List voices' conveys. It is distinguishable from siblings like render, validate, and job, though it never explicitly states that it is the discovery/enumeration 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?

The second sentence gives a downstream selection rule ('use a voice whose language matches the script'), which implies this is a lookup step to run before rendering. There is no explicit when-to-call guidance, no mention of alternatives, and no statement of prerequisites or that no arguments are needed.

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