find_replace_transcript_tool

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

With no annotations, the description carries the burden well: it discloses that dry_run changes nothing and returns a preview, that a non-dry run replaces all previewed matches atomically 'in one undo step,' and that 'replaced' gives the count. The one-undo-step and whole-word-match semantics are exactly the kind of behavioral context annotations would otherwise need to provide. It omits permission/auth and any rate or scope limits, keeping it from 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?

Front-loads the core verb+scope, then layers in match semantics, dry_run behavior, commit behavior, and the sibling routing. It is dense but every sentence earns its place; only the double-parenthetical backtick naming is slightly heavy for an agent-facing string.

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 labels (matches, count, replaced) need not be defined here, and the description focuses appropriately on behavior instead. For a destructive replace with no annotations, the atomic-undo disclosure is the key missing piece and it is present; the remaining gap is undocumented match_case/project_path parameters and no auth/prerequisite notes.

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% across 5 parameters, so the description must compensate and only partially does: it explains dry_run's effect and preview fields and implies search/replacement semantics via 'word or phrase.' match_case and project_path are left entirely undocumented in both schema and description, so the coverage gap is not closed.

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 (replace a literal word or phrase in the transcript) and adds precise scope: whole-word matching across every track and recording, with surrounding punctuation preserved. It also names the sibling it is not (correct_transcript_tool), so an agent can distinguish it without opening either 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?

Provides explicit routing: use this for multi-match find-and-replace, and "For one word use correct_transcript_tool," giving the alternative and its selecting condition. It also distinguishes the dry_run preview path from the commit path. It stops short of stating when-not-to-use relative to search_transcript_tool or correct_transcript_phrase_tool, so not a full 5.

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