Tutorial AI

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

Annotations already declare openWorldHint=false, destructiveHint=false, and idempotentHint=false, so safety and repeat-call behavior are covered structurally. The description adds genuine value with the notification side effect ('Comments notify project collaborators according to their notification preferences'), which is the kind of external consequence annotations can't express. However, it says nothing about permissions, what happens on an invalid anchor, or which anchor shape pairs with which anchorType.

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 with no filler; the primary branching logic (reply vs. new thread) is front-loaded and the side effect follows as secondary context. Every clause carries information an agent needs.

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 needn't be explained, and the notification side effect is a nice addition. Still, for a 5-parameter mutation tool with zero schema description coverage, an agent is left guessing about projectUid's role, what 'text' content is expected, and the anchor-shape-to-anchorType mapping — gaps that would likely cause a malformed first call.

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%, so the description carries the burden, and it partially discharges it by explaining the threadUid-vs-anchor mutual exclusivity and the anchorType/anchor pairing — semantics the raw schema does not express. But the two required parameters (projectUid, text) get no mention, and the description never maps anchorType 'text_range' to the wordStart/wordEnd variant versus 'generated_video' to the id/version/timestamp variant, leaving the anyOf ambiguous.

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 uses a specific verb-plus-resource framing ('Reply to threadUid, or start a thread') that makes the two operating modes of this tool immediately clear, distinguishing it from siblings like update_comment or delete_comment. It stops short of naming any sibling explicitly, so it lands at 4 rather than 5.

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 concrete routing logic: supply threadUid to reply to an existing thread, or supply anchorType plus anchor to open a new one. What's missing is negative guidance — nothing says what to do if both are supplied, or that update_comment is the tool for editing an existing comment.

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 only declare destructiveHint=false, idempotentHint=false, and openWorldHint=false; the description goes far beyond by disclosing the reverse-order behavior of repeated after inserts, the difference between returned placement and actual playback boundaries, and write-affecting conventions such as omitting settings.audio for silent video and requiring minDuration for silent slides.

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 critical insertion semantics are front-loaded, but the body is a single dense paragraph of roughly 350 words mixing anchor rules, placement semantics, slide-type rules, and media caveats with no headings or grouping. For a tool this complex the length is defensible, but the lack of structure costs it.

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 9-parameter mutation tool with deep nested objects, the description covers the correctness traps an agent would otherwise hit (reverse ordering, silent slides, muted-audio workaround, script-bound uid conventions). An output schema exists, so return values need not be explained.

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 already 89%, so the baseline is 3; the description adds real meaning on top by explaining what each anchor type resolves to, that after also accepts {type: "end"}, and the trailing-effect semantics of a composition-item anchor. Some content, like container uid naming and item counts, restates the schema's own descriptions, which keeps it from a 5.

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 opening sentence states a specific verb, resource, and anchoring model ("Insert a new slide before or after an explicit anchor"), which is enough to distinguish it from update_slide, remove_slide, and reuse_slide 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?

It gives explicit routing rules: exactly one of before/after, which anchor types each accepts, how to open a slides-only project, when to choose blank vs title vs list, and the dryRun-preview-then-approve workflow. Concrete alternatives and exclusions are named rather than 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?

Although annotations declare the safety profile (non-destructive, non-idempotent, closed-world), the description adds substantial behavior beyond them: bytes never traverse MCP, the caller must execute a returned PUT with exact bytes and returned headers, and explicit size caps per media type. It also warns against re-uploading on timeout, which is critical for a non-idempotent operation.

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?

Dense but front-loaded: format constraints, metadata requirements, size limits, and the PUT/poll workflow appear in that order with no filler. Every sentence carries procedural or constraint information an agent needs.

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 multi-step tool with a nested metadata object and an output schema, the description supplies everything the schema cannot: how to consume the returned uploadRequest, how bytes are transferred out-of-band, and how to confirm completion via list_assets.

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?

With 60% schema coverage, the description compensates by explaining that metadata width/height are pixels and required for every asset and that durationMs is only needed for MP4, plus the 5 MiB / 100 MiB limits. filename and mimeType semantics are left to the schema, so it stops just short of full coverage.

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 (create one asset from a local file) and enumerates the accepted MIME types. It is clearly distinguished from siblings like list_assets, which is referenced only as the polling destination.

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?

Gives explicit preconditions (file must be available locally, convert SVG/GIF to PNG first), the required metadata per asset, and a precise post-call protocol including the 2-minute polling window and the fallback behavior when the asset is still uploading.

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 openWorldHint=false, destructiveHint=false and idempotentHint=false, but the description adds real behavioral context beyond them: project lands in the recording's workspace, a canonical video segment is created, the script is auto-generated, and partial success leaves the project in place with scriptGenerated=false recoverable via retry_video_segment_script_generation. It does not warn that a repeat call creates a second project despite idempotentHint=false, which would have made this 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 action and the source tool, then the selection guardrails, then the failure-recovery path — a sensible order. It is somewhat long and the 'never select based on result order, recency, apparent relevance or a single-result list' enumeration could be tightened, but every sentence carries operational content.

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 an output schema present, return values needn't be explained, yet the description still clarifies the scriptGenerated=false semantics and the projectUid/projectSectionUid retry handoff, which is genuinely useful. Nothing critical is missing for a mutation tool with only three required params, though repeat-call/duplicate behavior is 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%, so all three parameters are already documented with provenance (list_screen_recordings, list_workspaces). The description's 'Pass the recording title unless the user chose another' largely restates the title field's schema description, adding no new syntax or constraint information. 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+resource ('Create a new project from a ready screen recording') and names the upstream source tool (list_screen_recordings), so the agent knows the precondition. It does not explicitly differentiate from the sibling generate_project, which is the closest ambiguous alternative.

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?

Gives explicit when-to-use ('call only when the user explicitly asks to create the project'), explicit recording-selection rules with prohibitions (never by result order, recency, relevance, or single-result list), and names the exact alternative for the partial-failure path (retry_video_segment_script_generation). Remaining ambiguity about which recording to use is resolved by routing back to the user.

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 only flag destructiveHint=true; the description supplies the non-obvious cascade rule that deleting a thread's first comment removes the whole thread, plus the caller-ownership restriction. Those are precisely the behavioral facts an agent cannot derive from the schema or annotations, and they directly alter invocation safety.

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, zero padding, with the cascade warning and confirmation instruction front-loaded where it will be read before the call is made.

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 destructive tool the safety behavior is well covered, and an output schema exists so return values need no explanation. The gap is parameter meaning: with both identifiers undocumented in the schema and absent from the description, an agent cannot tell what projectUid contributes.

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% for two required parameters, so the description carries the full explanatory burden and does not meet it — neither commentUid nor projectUid is mentioned, and their relationship (comment scoped within a project) is never stated.

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 ("Delete one of the caller's own comments") and adds an ownership scope, which implicitly separates it from update_comment and get_comments. It never names a sibling explicitly, so an agent must infer the routing, but the action is unambiguous.

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 one concrete operational guideline — ask for explicit confirmation before deleting a thread's first comment — and the ownership restriction implies what is out of scope. It does not say when to prefer this over update_comment or how to obtain the commentUid, leaving the broader usage decision implicit.

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 destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds valuable workflow context (the dependency on list_workspaces/list_folders and the user-confirmation step) but says nothing about what is copied, permissions required, or that repeated calls create separate copies.

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 short sentences, front-loaded with the action, then the prerequisite workflow, then the invocation guard. No filler, and the ordering matches how an agent would reason about calling it.

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 an output schema present, return values need not be explained, and annotations cover the safety profile. The description supplies the missing invocation preconditions and destination workflow; only minor details (copy semantics, permission requirements) are absent for a 3-parameter mutation 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 67% — toFolderUid and toWorkspaceUid are already documented in the schema, including the 'omit for workspace root' rule, which the description largely repeats. The undescriptioned projectUid gets no added meaning from the description either, so it does not compensate for the coverage gap.

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 ('Copy') and resource ('a project') plus destination scope (workspace and optional folder). This clearly separates it from sibling mutation tools like move_project or create_project_from_recording, which an agent could otherwise 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?

Explicitly gate-keeps invocation: 'Call this only when the user explicitly asks for a copy', and prescribes a prerequisite discovery workflow (call list_workspaces and list_folders before asking the user to choose). It also names the condition for omitting toFolderUid (workspace root).

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?

Beyond the annotations, it discloses that the tool returns HTML and does not persist anything, which is critical for an agent to know. It also prescribes the user-visible review step before saving, adding meaningful behavioral context that the annotations do not cover.

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 two sentences, front-loaded with the core action and immediately followed by the critical non-persistence caveat. Every sentence carries useful information without waste.

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 presence of an output schema means return values need not be fully described, and the description already notes HTML output. However, with no schema descriptions for the two parameters, the missing prompt semantics leaves the definition slightly incomplete for 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 description coverage is 0%, so the description needs to compensate for both parameters. It only implies projectUid through 'from the project' and says nothing about the prompt parameter or how it shapes the generated draft, leaving a significant semantic gap.

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: generate an AI document draft from a project. It clearly distinguishes this from get_document and save_document by noting that it returns HTML and does not save or replace the current document.

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 clear usage context: show the generated HTML to the user before entering any later save workflow. It implies save_document is the follow-up action but does not explicitly name that sibling or discuss other alternatives.

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 only cover openWorld/idempotent/destructive hints, so the description's disclosure that this is async, returns the queued generation rather than the finished video, and consumes generation quota is genuinely valuable. It stops short of warning that repeat calls are not idempotent and would burn quota again, or of describing failure 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?

Three tight sentences, front-loaded with the async/queued behavior and quota cost before defaults. The title sentence largely restates the schema's own title description, which is the only wasted motion.

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 an output schema present, return values need no explanation, and the description covers the critical async/quota semantics. Remaining shortfall is the undocumented generateDocument flag and no caution about double-triggering renders given idempotentHint=false.

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 only 14% (only title is documented), so the description must compensate: it supplies defaults for resolution, width, height and fps ('FHD, 1920x1080 and 30fps') that appear nowhere in the schema, and clarifies the title's dual effect. The gap is generateDocument, which is unexplained in both places.

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 and resource: 'Start an asynchronous video render for a project.' That distinguishes it cleanly from siblings like generate_document, get_project, publish_project, and retry_video_segment_script_generation without needing to name them.

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 async nature ('does not wait for the rendered video') and the quota cost imply when this is appropriate, but there is no explicit routing to alternatives (e.g. generate_document vs video render) and no when-not guidance. Usage is inferable rather than stated.

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 and openWorldHint=false, so safety is covered. The description adds real value by disclosing that deleted threads are excluded and that threads are returned together with their comments, but says nothing about ordering, pagination, or result size.

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 the verb first and zero filler. Nothing in it is redundant or out of order.

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 shape need not be described, and annotations cover the safety profile. However, with two parameters at 0% schema coverage, leaving anchorType entirely undescribed is a real gap an agent would hit when trying to filter by anchor type.

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%, so the description carries the full burden, yet it only implies projectUid via 'for a project'. The anchorType enum (generated_video vs text_range) — the one parameter that materially changes the result set — is never explained.

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 ('List non-deleted comment threads and their comments') plus a scope ('for a project'), which distinguishes it from the mutating siblings add_comment, update_comment and delete_comment. It does not explicitly name an alternative, so it stops short of a 5.

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 when-to-use guidance, no prerequisite statement, and no mention of alternatives such as get_project or get_document. The agent must infer that this is the read path for comments from the verb alone.

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 and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that document is null when nothing has been saved — which pre-empts a confusing empty result. It says nothing about permissions or size/format of the returned document, so it is incremental rather than rich.

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 with the action front-loaded and the null-result caveat second. No filler, though the second sentence could be folded in without loss.

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, and the null case is flagged. However, for a tool requiring an identifier, the description leaves the agent with no hint about sourcing projectUid, which is the main gap in an otherwise simple getter.

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 sole parameter projectUid is undocumented in both schema and description. The description does not explain what a projectUid is, where to obtain one, or whether it can come from list_projects/get_project, so it fails to compensate for the coverage gap.

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 ('Read the saved project document'), which contrasts implicitly with siblings like save_document and generate_document. It never names those alternatives, but the read-only framing makes the purpose unambiguous.

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 only implied: an agent can infer this is the way to fetch an already-saved document rather than generating one. There is no explicit statement of when to prefer this over generate_document or get_project, and no prerequisite or exclusion 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 readOnlyHint=true and openWorldHint=false. The description adds useful behavioral and domain context: it explains source-less sections, implicit remaining video when videoPlayback is absent, section uid versus videoSource.videoUid, and that exact timing requires the generated timeline. It does not mention permissions or rate limits, but it adds substantial semantics beyond the annotations.

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: it starts with what the tool returns, then gives structural caveats, then routes the agent to other tools for excluded data. Every sentence carries meaning, with no 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 the description need not document every return field, and it already covers the main content domains and important structural edge cases. Completeness is slightly reduced by the missing projectUid guidance and by not explicitly distinguishing this overview from list_projects or get_document.

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%, so the description should explain projectUid, but it does not mention the parameter at all. The parameter name is self-explanatory and required, but the description adds no 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 states a specific verb and resource ('Read the project overview') and enumerates the domains returned: identity, lifecycle, permissions, settings, publication, and sections with authored blocks. It also distinguishes the tool from nearby siblings by naming excluded content and pointing to get_script_rewrite_context, get_slide, and list_assets.

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 says what this tool does not return and names alternatives for narration content, slide trees, assets, and complete video objects. The main gap is that it does not explicitly contrast the project overview with list_projects, get_document, or get_script_rewrite_context beyond exclusion notes.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful semantics about how section markers own content, what the protected video-playback token does, and when footage plays at section end. However, it omits any statement about permissions, size limits, or behavior when a project is missing or has no script.

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 purpose is front-loaded in the first sentence, which is good. But several sentences are dense and of unclear value to tool selection, notably 'The section and slide registries do not define playback adjacency' and the closing 'The Tutorial AI backend does not call another AI model,' which reads as an internal note rather than selection-relevant 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?

An output schema exists, so the extensive return-shape narration is largely redundant, but it does establish important conventions (authored document order, section ownership, playback fallback). Combined with readOnly annotations, an agent has enough to call it correctly; the only material gap is the undocumented projectUid.

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 one required parameter, projectUid, and schema description coverage is 0%, so the description carries the full burden of explaining it. The description never mentions projectUid or what kind of identifier it expects (project UID vs. slug, where to obtain it). The remaining text is entirely about return structure.

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 concrete verb and resource: 'Read the complete script for rewriting by the LLM in this MCP session.' This distinguishes it from the mutation sibling rewrite_script by making clear it only fetches context. It does not explicitly contrast with get_document or get_project, so the differentiation is implied rather than spelled out.

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 'for rewriting by the LLM' implies the tool is a prerequisite read before a rewrite, but no explicit when/when-not guidance or named alternative is given. An agent must infer that this should be called before rewrite_script rather than after or instead of 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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: the null 'element' case for older or externally modified projects with script markup but no stored layout, which tells the agent not to treat null as an error.

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 action and identifier, with the edge case relegated to second position. No filler and nothing repeated from the 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?

Since an output schema exists, the description needn't document return structure, and it correctly stays brief while covering the one surprising return state (null element). The remaining gap is projectUid's role, which is left to the schema and is undocumented there too.

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 50% — slideUid is documented, projectUid is not. The description reinforces that slideUid is a *stable* identifier (as opposed to an index) and that it selects exactly one slide, but it says nothing about projectUid or how it scopes the lookup, leaving the uncovered half of the schema unaddressed.

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 one slide') and names the keying mechanism ('by its stable slideUid'), plus what comes back ('stored visual layout and on-screen text'). It's clearly distinct from get_project/get_document/update_slide, though it never explicitly contrasts itself with them.

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 only implied — the read framing plus the 'stable slideUid' hint tells the agent this is the lookup path for a single known slide. There is no explicit when-to-use guidance, no mention of when to prefer get_document or a listing tool instead, and no stated prerequisites.

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 only declare the safety profile (non-destructive, non-idempotent, closed-world); the description adds substantive behavior the annotations cannot convey: narration is auto-generated and saved in the supplied language, a slide UID at a narrated internal boundary may be refused, and scriptGenerated=false signals a partial-success state that must not be re-inserted. It also encodes a user-consent requirement, which is important for a mutating 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?

Front-loaded with purpose and the recording-selection guard, then placement, then the retry path — a sensible order. It is on the long side, and the sentence about slide UIDs at narrated boundaries repeats the anchor parameter description nearly verbatim, so there is some redundancy against the schema.

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 an output schema present, return values need no explanation; the description instead covers everything else an agent needs: workspace membership constraint, language generation, anchor selection strategy, consent gating, and the recovery path when script generation did not occur. Nothing material is missing for a 5-parameter mutating 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 baseline is 3, but the description adds real meaning: the language defaulting rule (project language from get_project, else en-US), title defaulting to the recording title, and which anchor kinds are reliable versus refusal-prone. The anchor guidance is partly duplicated in the schema's own anchor description, which keeps this just short of a 5.

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 ("Insert a ready screen recording ... into an existing project") and identifies the upstream source tool (list_screen_recordings), which cleanly separates it from create_project_from_recording and the slide-level siblings. An agent can distinguish it 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?

Gives explicit preconditions ("Call only when the user explicitly asks for this change", recording must belong to the project workspace), an anti-pattern with reasoning (never choose by result order/recency/single-result), and a named alternative for the already-inserted case (retry_video_segment_script_generation with returned ids). This is when/when-not/alternative guidance in full.

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 only declare readOnlyHint and openWorldHint; the description adds the real behavioral load: page cap of 100, one-page-per-call pagination, a 2-minute polling ceiling for upload status, and the explicit fallback 'background upload finalization is unavailable' when polling fails. Those operational traits are exactly what an agent cannot infer from annotations alone.

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?

Purpose is front-loaded in the first sentence, and the remaining sentences each carry operational guidance. It is slightly dense and repeats the 100 cap already in the schema, but nothing is wasted 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 filtered, paginated list tool with an output schema and read-only annotations, the description covers scope, polling lifecycle, pagination limits, and how to report counts correctly. An agent has everything needed to call it and interpret results without guessing.

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 defines type, limit, offset and query semantics. The description echoes the 100-asset cap and workspace scoping but adds no new parameter syntax or format detail beyond what the schema states, 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 with explicit scope: 'List the images and videos stored in one workspace.' No sibling tool performs listing of assets, so the agent can route here without comparing schemas, and the sentence also implies the workspace-scoped boundary.

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?

Gives concrete downstream usage (place assets on slides via update_slide/add_slide), tells the agent to poll after a local upload and for how long, and warns to answer 'how many' from total. It stops short of naming explicit alternatives or exclusions, so it is strong context rather than full when/when-not routing.

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered elsewhere; the description still adds real behavior beyond that: trashed folders are excluded, nesting must be reconstructed from parentUid, and the workspace root is not a folder. It does not mention ordering or completeness of the listing, which would round this out to 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?

Four tight sentences, each doing distinct work: scope, nesting reconstruction, workflow hand-off, and the root edge case. The core action is front-loaded and nothing is repeated from 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?

Output schema exists so return shape needn't be described, and annotations carry the read-only profile. What remains — how to present results, how to remap the uid into move_project/duplicate_project, and the root caveat — is fully covered for a one-parameter listing 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% for the single workspaceUid parameter, so the baseline is 3. The description goes further by explaining the downstream semantics of the returned uid (toFolderUid) and the null/omitted case for root, meaning that would otherwise be undocumented at the call site.

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?

Specific verb and resource ("List every non-trashed folder in a workspace") with a scoping qualifier ("where the user can move or copy projects") that no sibling tool covers. An agent can distinguish it from list_projects and list_workspaces without opening a 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?

Explicitly states the consumption path: present names/paths to the user, then pass the chosen uid as toFolderUid to move_project or duplicate_project. It even handles the negative case — omit toFolderUid when the workspace root is selected — so the agent knows exactly what to do with each outcome.

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 readOnlyHint=true and openWorldHint=false, but the description adds substantial behavioral detail beyond that: pagination is capped at 100, hasGeneratedVideo and publishUrl are independent facts, and generatedCount/publishedCount are computed before filters and may overlap. This is exactly the kind of return-value and counting semantics an agent needs.

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 purpose is front-loaded in the first sentence, and each subsequent sentence adds a distinct operational fact: field meanings, return shape, pagination cap, count derivation, and how to answer 'how many' questions. 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?

With six parameters, an output schema, and read-only annotations, this description covers what the tool returns, how pagination works, how the count fields differ from the page, and how filters affect counts. Nothing essential for correct invocation or interpretation appears to be 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 every parameter already has its own documentation, including limit, query, offset, published, workspaceUid, and hasGeneratedVideo. The description does not add syntax or format details for individual parameters, so the baseline score of 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 and resource: 'List the Tutorial AI projects this user can access.' The plural 'projects' and access scope make it clearly distinct from the sibling get_project tool, which retrieves a single project.

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 states how to answer count questions using total/generatedCount/publishedCount rather than the returned page, which is useful operational guidance. However, it does not explicitly say when to use this tool versus alternatives such as get_project, nor does it name any exclusions or prerequisites beyond the implicit listing context.

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 and openWorldHint=false, so safety is covered. The description adds meaningful behavior: return fields {recordings, total, hasMore}, a 100-item page cap, and the important rule to use total rather than counting returned recordings.

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 with no waste. The purpose and scope are front-loaded, followed by return-shape details and a precise counting instruction.

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?

Complete for this list tool: the schema fully documents parameters, annotations cover the read-only safety profile, and an output schema exists. The description still usefully clarifies pagination and total-count behavior without overexplaining return values.

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 schema documents workspaceUid, limit, query, and offset thoroughly. The description reinforces workspace scoping and the 100 cap, but does not add parameter semantics beyond what the schema already provides, 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 ("List screen recordings") plus scope ("one workspace") and readiness condition ("ready to create a project from or insert into an existing project"). This distinguishes it from sibling action tools like create_project_from_recording and insert_recording.

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 frames the use case: finding recordings that can become a new project or be inserted into an existing one. It does not explicitly name exclusions or say which sibling action to call next, but the context is strong enough for correct 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds non-obvious behavior: results are paginated with total/hasMore, and when filtering by language each voice returns only the matching language metadata — a subtle shaping of the response an agent could easily miss.

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?

Four tight sentences: capabilities first, then filtering, then pagination, then the downstream link. Zero filler; each sentence carries actionable content.

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 spelled out, yet the description still flags total/hasMore for pagination. With the two undocumented params covered through prose, nothing an agent needs in order to call this 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 coverage is 50%: limit and offset are documented in schema, while query and language are bare. The description compensates by explaining that `query` matches text in name, tone, gender or nation and that `language` takes a code or locale with concrete examples, adding meaning well 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?

Specific verb+resource ('List selectable narration voices') followed by an enumeration of returned fields (id, display name, tone, gender, nation, languages). It is clearly distinguishable from the mutation sibling set_voice, which it names 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?

Gives concrete filter examples ('hu' or 'hu-HU') and tells the agent how to continue pagination with total/hasMore plus offset, and what to do with results ('Use the returned id with set_voice'). No explicit when-not-to-use case, but the guidance is well beyond implied usage.

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 and openWorldHint=false, so safety is covered; the description adds that the response also carries the user's display name and instructs how to present results (by name) before passing the uid onward. It doesn't cover edge cases such as zero workspaces, but the behavior described is accurate and additive.

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 short sentences: what it returns, when to call it, then what to do with the result. The chaining instruction is front-loaded and nothing is redundant.

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 zero-parameter, read-only discovery tool with an output schema and annotations already in place, the description supplies everything missing: the trigger, the display convention, and the next call to make with the returned uid.

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 the baseline is 4. The only field mentioned, workspaceUid, belongs to the sibling call rather than this schema, but it is correctly framed as a hand-off token rather than an input here.

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+resource ('Get the current user's display name and the workspaces they belong to'), which is clearly distinct from sibling listers like list_projects, list_folders and list_assets. It also names the exact field (workspaceUid) the agent will need downstream.

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?

Gives explicit trigger conditions: 'when the request does not identify a workspace' or 'when a destination workspace must be selected'. It also spells out the follow-up step ('pass the selected uid as workspaceUid to list_projects'), which is the alternative-selection guidance an agent needs.

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 destructiveHint=true and idempotentHint=false, and the description adds real behavioral context: source preservation only applies to same-workspace moves, while cross-workspace relocation follows backend project rules. The phrase 'according to its normal project rules' is vague, leaving the exact cross-workspace consequence (e.g., whether assets are re-scoped or IDs change) undisclosed.

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 sentences, front-loaded with the action, then prerequisites, then the data-preservation caveat. Mostly efficient, though the closing clause about 'normal project rules' is low-information filler for a destructive operation.

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 3-parameter mutation tool with an output schema present, the description covers the action, the prerequisite discovery calls, and the parameter-omission rule. The residual gap is the destructive consequence of cross-workspace movement, which is only gestured at rather than explained.

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 67%, with toFolderUid and toWorkspaceUid already documented in the schema. The description reinforces the omit-to-use-root rule and implies the workspace/folder relationship, but adds nothing about projectUid (the undocumented parameter beyond its name) or about UID format/validity.

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 ('Move a project') plus the destination dimensions (workspace, optionally folder), which cleanly separates it from sibling operations like duplicate_project, update_project, and delete-style tools. An agent can identify the operation and its scope 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?

Gives concrete pre-call workflow ('Call list_workspaces and list_folders before asking the user to choose the destination') and a conditional rule ('Omit toFolderUid only when they choose the workspace root'). It does not mention alternatives such as duplicate_project when the user wants a copy rather than a relocation, 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.

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false, so the safety profile is partly covered. The description adds useful scope ('one render version only, not translation siblings') and a confirmation requirement. However, it never explains the destructive aspect itself – whether publishing replaces an already-published version, and whether it can be undone – which is the key unknown for a destructive 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?

Three short sentences with zero filler; the core action is front-loaded and the scope caveat and confirmation rule follow in priority order. Every sentence carries non-redundant 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 described. But for a destructive, non-idempotent, two-parameter mutation with 0% schema coverage, the description leaves the parameters undefined and the destructive consequences unstated. It is minimally callable but not fully specified.

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%, so the description carries the full burden, and it largely fails. It references 'version' twice but never says it is a render version identifier/number or how to obtain it, and it never mentions the required projectUid parameter at all. An agent has to infer both parameters from names alone.

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 with scope: 'Publish one completed render version of a project.' The added 'does not publish translation siblings' narrows what the action touches. It does not name the obvious sibling alternative (unpublish_project), so differentiation is implied rather than explicit.

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?

Gives a concrete workflow constraint: 'Ask the user to confirm the exact version before making it public.' It also implies the precondition that the version must be a completed render. It stops short of telling the agent when to choose this over unpublish_project or translate_project.

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 destructiveHint=true and idempotentHint=false, yet the description still earns credit by detailing the blast radius (atomic removal of markup, narration, text, element tree) and the non-obvious side effects (media files survive; orphaned assets are detached). It stops short of stating irreversibility or any restore path, which keeps it below 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?

Four tight sentences with the scope and destruction list front-loaded, followed by the safety workflow and then the side-effect caveat. No sentence is filler; each adds an actionable fact.

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, and the description fully covers what a destructive tool needs: what is destroyed, the atomicity guarantee, the dry-run approval gate, and the asset/media aftermath. Nothing an agent needs to invoke it safely 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 coverage is 67%, and the description meaningfully supplements it by stating where slideUid comes from (get_slide) and by instructing that dryRun be used before the real call. projectUid is left entirely unexplained in both the description and 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 opens with a specific verb and scope ('Delete one whole slide') and enumerates exactly what is removed: script markup, narration, on-screen text, and the stored element tree. That list makes it unmistakable against siblings like update_slide or add_slide without needing to open 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?

It prescribes a concrete workflow: call with dryRun: true first, summarize what would disappear in user language, then wait for approval, and it names get_slide as the source of the slideUid. That is explicit when-and-how guidance rather than implied context.

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?

Goes beyond the destructiveHint=true annotation by scoping the blast radius: no new project or video segment is created, but automatically generated slides are not recreated — which is exactly the destructive consequence an agent needs to warn about. It does not say what happens to any pre-existing narration on that segment or note performance/cost, so it stops short of full disclosure.

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?

Four tight sentences ordered by importance: purpose, triggering condition, argument provenance, blast radius, then the user-consent gate. No filler and nothing is buried.

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 destructive, non-idempotent retry tool with a rich output schema, the description covers trigger condition, required inputs and their source, side effects, and the consent policy. Return values are covered by the output schema, so nothing material 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 all three params (including the language fallback rule and its pattern) are already documented. The description's 'use exactly the UIDs returned by that operation' adds a useful provenance constraint but largely restates the schema's uid descriptions, and the required language param is not addressed in the description at all. 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?

Specific verb+resource: 'Retry narration generation for a video segment', with the triggering condition named. It is clearly distinguished from the sibling operations that create the segment in the first place (create_project_from_recording, insert_recording).

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 precondition ('when create_project_from_recording or insert_recording returned scriptGenerated false'), explicit source of the arguments ('use exactly the projectUid and projectSectionUid returned by that operation'), and an explicit exclusion ('Call only when the user explicitly asks to retry'). All three when/when-not/which-input axes are covered.

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?

Goes well beyond the annotations by disclosing that the server loads and remaps the source slide, that repeated inserts against one anchor land in reverse order, and that an approval gate exists. Minor gap: it does not say what happens to copied assets/media or whether a source project without read access yields a distinct error.

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 front-loaded sentences with no filler: purpose first, then the exactly-one-of constraint, then the ordering pitfall and approval gate. Each sentence carries a distinct, actionable rule.

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 an output schema present, return values need no explanation, and the description covers the authoring rules an agent needs (anchor choice, ordering, approval). Slightly incomplete on source-access failure modes and on how the returned placement differs when implicit playback makes a placement internal.

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 only 40%, and the description compensates only partially: it explains the exactly-one-of rule for before/after and points to add_slide's anchor vocabulary, but sourceProjectUid, sourceSlideUid, and targetProjectUid are undocumented beyond their names. The reverse-order behavior for a shared 'after' anchor is the most valuable added semantic.

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 with scope: 'Copy one slide from another accessible project in the same workspace.' It is immediately distinguishable from add_slide (which it references for anchors) and duplicate_project (whole-project copy).

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 constraints: 'Provide exactly one of before or after', 'never send copied slide JSON or markup', and 'Call only after approval'. It routes anchor semantics to add_slide rather than restating them, and covers when-not via the no-JSON prohibition.

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 flag destructiveHint=true and idempotentHint=true, but the description adds real substance: existing slide narration and on-screen text may be overwritten, while slide structure is untouched. It also discloses the invariant the validator enforces (each protected token exactly once, in relative order) and how keyframe labels map tokens. It does not state explicitly that prior script content is fully replaced, which would close the loop on destructiveness.

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?

Four sentences, front-loaded with the verb and the source tool, then constraints, then scope boundaries. Dense but every sentence carries a distinct rule. Terms like 'protected token' and 'keyframe labels' are used without definition, which forces some inference.

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 an output schema present, return values need not be explained, and the description covers modes, edit latitude, token invariants, and tool boundaries. The remaining omission is the meaning/format of projectUid and any failure behavior for validation errors, which matters for a destructive write 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 67% and the schema already documents dryRun and content. The description goes beyond it by constraining content semantics: it must be complete, must include every protected token exactly once and in relative order, and may restructure paragraphs freely. projectUid remains unexplained in both places, a minor residual gap.

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 specific verbs (validate or save) against a specific resource (complete script content) and ties the input to get_script_rewrite_context, so the agent knows this is the write-back counterpart to that read tool. It also explicitly cedes slide structure to the slide tools, separating it from update_slide/add_slide 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?

The description names the prerequisite source (content produced from get_script_rewrite_context in this session) and the two modes implied by 'validate or save'. It also draws the exclusion boundary: 'slide structure is read-only and belongs to the slide tools.' It stops short of explicitly recommending a dryRun pass before saving, which would be the natural next 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 declare destructiveHint=true and idempotentHint=false, and the description corroborates this by saying the tool 'replaces the saved document' and requires user approval of exact title and HTML before the call. It does not spell out what prior content is discarded or whether prior versions are recoverable, which is the main remaining 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 sentences, no filler, front-loaded with the verb and create/replace semantics, followed by the required pre-call workflow. Each sentence carries a distinct, actionable fact.

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 the description does not need to explain return values, and annotations cover the safety profile. The approval workflow is fully described; only the handling of pre-existing content and the role of projectUid remain underspecified.

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 only 33%, so the description has to compensate. It adds meaning for title (show the exact title to the user) and content (approved HTML), but projectUid has no semantics in either the schema or the description, leaving one of three parameters opaque.

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 ('Save approved document HTML to the project') and disambiguates the create-vs-replace behavior in the same breath. An agent can separate this from generate_document and get_document 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?

Explicitly states the pre-call protocol: call get_document first when replacing, show the exact title and HTML to the user, and wait for approval. This is a concrete when-to-use/how-to-use rule rather than an implied one.

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?

Adds value beyond the annotations by bounding the blast radius ('changes only settings.voice.id'), which tells the agent the change is narrowly scoped despite destructiveHint=true. The validity constraint on the input is also behavioral context the annotations do not carry. No mention of what happens on an invalid voice ID or how errors are surfaced.

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 short sentences, front-loaded with the action, then the input constraint, then the scope of the effect. No filler and every sentence adds 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 no explanation, and the scope clause covers the main behavioral risk. Still missing how to discover valid voice IDs, what happens if the ID is unknown, and any permission expectations for a mutating 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 description coverage is 0%, so the description must carry parameter meaning. It explains voiceId (an identifier for a known Tutorial AI voice) but never mentions projectUid, leaving half the parameters documented only by name.

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 ('Set the project-wide narration voice') and pins the target to a single setting ('changes only settings.voice.id'). It is distinguishable from list_voices (read) by the mutating verb, though it never names the sibling that supplies valid IDs.

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 voice must be a known Tutorial AI voice' implies the caller should first resolve IDs via list_voices, but this is left implicit. There is no explicit when-to-use/when-not-to-use or prerequisite statement.

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?

Beyond the annotations, the description discloses important behavior: a new language creates a sibling project, an existing language retranslates and replaces that sibling's editable translated content while preserving its uid, and the call uses the workspace's one-click translation entitlement and may incur AI usage. This is strong transparency for a destructive operation and is consistent with destructiveHint=true.

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 operation and followed by behavioral consequences and the confirmation requirement. Every sentence carries actionable meaning with no 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 values need not be described. Given the destructive annotation, two required parameters, and the create/retranslate distinction, the description provides the behavioral context an agent needs to call the tool safely and 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 50%, with targetLanguages documented in the schema and projectUid undocumented. The description adds useful semantics for targetLanguages by explaining create-vs-retranslate behavior, but it does not add meaning for projectUid beyond the obvious name. This is reasonable but not fully compensating for the coverage gap.

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 precise verb and resource: translating a project into one or more target languages in its current workspace. It also distinguishes two distinct outcomes, creating a sibling project versus retranslating an existing one, which lets an agent understand the operation 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?

It clearly explains the two usage scenarios (new language creates a sibling; existing language retranslates and replaces content) and instructs the agent to confirm target languages with the user before calling. It does not name or compare against sibling tools such as generate_project or duplicate_project, so it stops short of explicit alternative routing.

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?

The destructive and idempotent annotations already cover safety and repeat-call behavior. The description adds meaningful context beyond annotations by saying translation siblings are unaffected and by requiring explicit user confirmation.

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 short sentences, front-loaded with the action and followed by two relevant constraints. Every sentence contributes useful 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 the annotations already disclose destructiveness and idempotency. The main remaining gap is that projectUid semantics are not described.

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%, so the description must carry the parameter meaning. It only says "one project" and does not explain projectUid format, source, or required status beyond what the parameter name already implies.

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: "Remove the current public video for one project." The scope is precise and the note about translation siblings distinguishes it from broader project deletion or translation operations.

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?

Clear usage context: use it to remove the current public video for one project. It also explicitly requires asking the user for confirmation before calling, though it does not name publish_project as the alternative action.

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 destructiveHint=true and openWorldHint=false, so the safety profile is partly covered. The description adds real value by making clear that the existing text is replaced (i.e. prior content is lost) and that only the caller's own comments in the given project can be modified. It does not describe the failure mode for a non-owned comment, which keeps it short of 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 short sentences, both front-loaded with the action first and the constraint second. Nothing is repeated from the schema and there is no 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 and annotations cover the safety profile, so the description need not explain return values. But for a destructive update with three undocumented, required parameters at 0% coverage, the definition should say whether 'text' replaces the whole comment and what happens on ownership or project mismatch.

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%, so the description has to carry the load: it clarifies that projectUid scopes the ownership check and that commentUid identifies the caller's own comment. It adds no format or sourcing details for the UID strings and does not clarify that 'text' is a full replacement rather than a patch, leaving meaningful gaps.

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?

'Replace the text of one of the caller's own comments' gives a specific verb (replace), a specific resource (comment text), and an ownership scope. It is immediately distinguishable from add_comment, delete_comment, and get_comments 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 prerequisite 'the comment must belong to projectUid' is stated, which is useful selection context. However, there is no explicit guidance on when to use this instead of add_comment or delete_comment, and the 'own comments only' restriction is stated without saying what to do otherwise. Usage is implied by the tool name rather than spelled out.

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?

It adds behavior beyond the annotations: showDocumentOnSharePage is translation-group-wide, so changing it on one member affects every sibling; this explains the destructiveHint=true annotation. It also clarifies that language only sets a narration tag and does not translate anything, and that the result matches get_project after the write. Nothing contradicts the declared non-idempotent, destructive 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?

It front-loads the writable fields first, then the patch rule, then exclusions, then the important caveat, then the confirmation instruction. Every sentence carries a distinct constraint, and there is no restatement of the name.

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 4-parameter mutation tool, this covers the mutations, the non-negotiable confirmation step, scope side effects, and the return shape by reference even though an output schema exists. Nothing an agent needs in order to call it safely 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 coverage is only 50%, so the description must compensate, and it does: it specifies patch semantics (omitted fields untouched), the at-least-one constraint that the schema does not encode, and the non-obvious scope of showDocumentOnSharePage. The language semantics are disambiguated beyond the enum list.

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?

A clear verb and resource, naming exactly the three fields that may be changed. It also explicitly states what the tool does not reach, naming the rewrite_script and update_slide siblings, so an agent can distinguish this tool from those siblings without opening their 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?

It states the selection rule: at least one field must be named, omitted fields stay untouched, and the other siblings hold the other settings. It also gives a procedural rule: ask the user first and pass the exact approved value.

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 only declare destructiveHint=true, idempotentHint=false, openWorldHint=false; the description goes far beyond by disclosing atomic whole-tree validation, last-write-wins concurrency semantics, which mutations are rejected (reordering/adding script-bound containers or their items), what is freely editable (settings, free image/video/text, existing item text), and z-order semantics of the element array. That is exactly the failure-mode detail a destructive mutation tool needs.

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-loaded with the core action and validation contract, then progresses to edit rules and narrow edge cases. It is long and a few clauses (muted-audio re-encoding, silent-audio re-encode warning) are niche, but each sentence encodes a distinct rejected mutation rather than restating structured data.

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 destructive, whole-tree replacement tool with a 10-branch recursive schema, the description supplies the missing behavioral layer: atomicity, conflict semantics, validation via dryRun, and the script-mirroring constraint that explains why certain structural edits fail. With an output schema present, return values need no explanation, so nothing essential 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?

With only 33% schema description coverage, the description carries most of the burden for `slide` and does so well: preserve the root uid, don't invent roles, don't omit untouched branches, element order equals z-order, and leave settings.audio off for silent video. It also extends `dryRun` beyond the schema's one-liner by framing it as validate-and-preview before approval. `projectUid` is never mentioned, which is the only gap.

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 ("Replace") and resource ("one stored slide") plus the exact shape expected ("a complete validated SlideElement tree"). It also names the sibling it routes to/from (get_slide first, add_slide for media-only slides), so an agent can distinguish it from add_slide, get_slide, and reuse_slide 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?

Gives an explicit workflow (call get_slide, copy element, edit, send whole result) and explicit when-not rules for several tempting-but-wrong paths: don't strip title/list containers, don't simulate a media-only slide by deleting a script-bound container, use add_slide with sectionType blank instead. Also prescribes dryRun: true for preview before approval.

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