Tutorializer Video Tutorials

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds the crucial warning about non-idempotency and the need to list projects first, which is valuable context beyond the annotations. It doesn't contradict any annotation and adds meaningful behavioral detail.

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

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

Two sentences with zero fluff: the first states the core purpose, the second delivers the critical caveat. Information is front-loaded and every word earns its place.

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 tool has an output schema (per context signals), so return format is covered elsewhere. The description covers purpose, usage warning, and behavioral nuance. For a create tool with one required parameter, this is complete enough for an agent to call it correctly.

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

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

Schema description coverage is 100%, so all parameters (name, domain, defaultLocale) are already documented with descriptions. The description adds no parameter-specific semantics beyond what the schema provides, so the baseline 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 explicitly states 'Create a Tutorializer project' with a specific verb and resource, clearly distinguishing it from the sibling tools which are all read/delete/update operations. No ambiguity about what the tool does.

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

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

Provides explicit usage guidance: warns that the call is non-idempotent and advises to list projects first to confirm the intended name. This gives the agent a clear precondition for safe use, though it doesn't mention alternatives (none exist among siblings).

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

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

Annotations mark the tool as non-read-only and non-idempotent, and the description expands on this by disclosing that synthesis consumes organization credits, is billable, and that repeating the call creates another segment and synthesizes again. This is exactly the kind of behavioral context an agent needs before invoking a state-changing 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 information-dense sentences with no filler. Purpose, billing implications, the url alternative, and non-idempotency are all communicated efficiently and front-loaded.

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 state-changing, billable tool, the description covers all critical operational facts: new segment creation, credit consumption, the url escape hatch, and repeat-call behavior. Parameters are fully documented in the schema and an output schema exists, so the agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so all six parameters are already documented. The description adds context about text-versus-url behavior but does not need to explain projectId, language, voice, or translatedText, 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?

States a specific verb and resource: 'Create one Tutorializer voiceover segment for a project.' It also distinguishes two modes—synthesizing from text versus registering a url—so the agent understands exactly what the tool does and how it differs from other create_* tools.

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

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

Clearly explains when to use the synthesis path versus passing a url to register already-produced audio. It does not explicitly name sibling tools like update_speech as alternatives, but the within-tool usage decision is fully specified.

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 carry readOnlyHint=false, idempotentHint=false, and destructiveHint=true, so the safety profile is known. The description adds valuable behavioral context beyond annotations: repeating the call creates another tutorial, and this action records a definition rather than rendering a video. No contradiction with 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 two sentences with no wasted words. It front-loads the core purpose, then packs the non-idempotency warning and the video distinction into compact, meaningful clauses. Every sentence earns its place.

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, all parameters are described in the input schema, and annotations cover the read-only/idempotency/destructive profile. The description supplies the missing behavioral nuance about duplicate creation and clarifies the tool is not for video rendering. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema fully documents name, projectId, and defaultVoice. The description adds no parameter-specific detail, but it does reinforce the importance of the name through the duplicate warning. Baseline 3 is appropriate given the high schema 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?

Description states a specific action and resource: 'Create a Tutorializer tutorial definition inside a project.' It also distinguishes itself from video creation by noting it records the tutorial but does not record or render a video, which clearly separates it from siblings like create_video and create_speech.

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 tells the agent to list tutorials and confirm the intended name first because repeated calls create duplicates. It also clarifies this tool does not record/render a video, providing a useful exclusion. It stops short of explicitly naming an alternative tool, but the guidance is clear and actionable.

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 readOnlyHint=false, idempotentHint=false, and destructiveHint=true. The description goes beyond these by spelling out the exact consequence of non-idempotence ('repeating the call registers a second output') and by clarifying that the tool does not perform recording, rendering, or uploading. No contradiction with the annotations is present.

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 with no filler: the first states the action, the second states the side effect, and the third states the boundary. The critical non-idempotence warning is front-loaded early, and every sentence earns its place.

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 tool has 13 parameters, an output schema, and informative annotations. The description supplies the missing conceptual context: what kind of video this is, that it must already be uploaded, that execution is non-idempotent, and that no media generation is involved. Nothing critical is left unexplained for an agent to invoke the tool 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 85%, so the schema already documents most parameters. The description adds only light grouping of locale, device, dimensions, and media URLs, and repeats the public https URL requirement already stated in the schema. This meets the baseline but adds limited new parameter-level meaning.

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 ('register') with a clear resource ('one already-uploaded rendered tutorial video') and enumerates what is recorded: locale, device, dimensions and media URLs. This distinguishes it from sibling create tools like create_tutorial and create_speech, which create different resources.

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 explicitly states the precondition: host the video file first and pass its public https URL. It also clearly says what this tool does not do — record, render or upload — making the boundary and usage context unambiguous. Repeating calls registering a second output also warns against unintended reuse.

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?

Even though annotations already flag destructiveHint and idempotentHint, the description adds crucial context: exactly what gets destroyed, permanence of deletion, and the recovery cost in re-synthesis and credits. This meaningfully raises the agent's awareness of consequences beyond the structured 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?

Two sentences, minimal filler, and well structured: the core action is front-loaded, followed by the essential permanence/cost caveat. Every clause earns its place.

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 one-parameter, single-purpose deletion tool with an output schema present, the description covers all decision-relevant facts: operation scope, idempotence, permanence, and recovery implications. Nothing needed to invoke it correctly is missing.

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

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

The input schema already fully documents speechId with 'Speech id to delete', so the description adds no additional per-parameter meaning. With 100% schema coverage, 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?

States a specific verb ('Permanently delete'), a precise resource ('one Tutorializer speech record plus its S3 audio and alignment files'), and clearly distinguishes this from sibling delete_video and other project/speech tools. An agent can immediately understand what the tool acts on and with what effect.

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 makes the intended usage clear: use this tool when a speech record and its stored audio/alignment files should be removed. It does not explicitly name alternatives or when-not-to-use conditions, but the specialized resource scope gives sufficient context for 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?

The description adds meaningful behavioral context beyond the annotations: the deletion is permanent, the definition must be authored again to restore it, and related rendered assets are left intact. This gives the agent a full picture of the operation's side effects.

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 concise sentences front-load the core action, then add idempotence, irreversibility, and scope exclusions. Every sentence earns its place without redundancy.

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

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

For a one-parameter delete tool with strong annotations, idempotence and destructiveness are covered, and the description explains what is and is not deleted. The presence of an output schema means return-value documentation is not required here.

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 there is only one parameter, tutorialId, which the schema already documents as 'Tutorial id to delete.' The description does not add further parameter meaning, so a 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 states a specific verb and resource: 'Permanently delete one Tutorializer tutorial definition.' This distinguishes it from sibling tools like delete_speech and delete_video by explicitly limiting scope to the tutorial definition.

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 clarifies that rendered videos and voiceover segments are not deleted by this tool and must be removed separately, which is a clear when-not guidance. It does not explicitly name delete_video or delete_speech as alternatives, but the sibling context makes the intended routing clear.

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 provide destructiveHint=true and idempotentHint=true, but the description adds valuable context: it specifies the exact deletion scope (record plus primary S3 object) and notes that restoration requires re-upload or regeneration. This goes beyond the annotations and clarifies consequences.

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

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

Two sentences with no redundant wording. The first sentence front-loads the primary action and scope; the second adds idempotency and recovery context. Every word earns its place.

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

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

For a single-parameter delete tool with annotations covering destructive/idempotent behavior and an output schema present, the description provides sufficient context: what is deleted, permanence, and recovery path. It lacks explicit permission or error info, but those are not critical for this simple operation.

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% and the parameter videoId is described as 'Rendered video id to delete'. The description reinforces that this id refers to a Tutorializer rendered-video record, but adds no new technical details. Baseline 3 is appropriate for high schema 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?

The description clearly states the verb 'Permanently delete' and the resource: 'one Tutorializer rendered-video record and its primary S3 object'. This is specific and distinguishes it from sibling delete_speech, which targets speech records. The resource 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 implies this tool is for deleting rendered videos, and the sibling list includes delete_speech for speech. However, it does not explicitly state when to use this versus delete_speech or any other alternative. The idempotency note gives behavioral guidance but not selection 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds context about the contents and Markdown formatting but does not cover failure behavior or authorization, and it is consistent with 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?

Two sentences front-load the action and object, then specify return contents. There is no filler, tautology, or redundant background.

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 one-parameter read-only tool with a full output schema and robust annotations, the description covers the identifier forms and result scope adequately. It is only mildly incomplete as a standalone guide because it leaves the choice against the other project-detail siblings implicit.

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

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

The schema already documents projectId as 'Project id or stable public vanity id' with 100% coverage. The description contributes only the word 'immutable', a minor elaboration, so it does not move meaningfully above the schema baseline.

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

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

The description opens with a specific verb and resource ('Fetch a single Tutorializer project') and clarifies the identifier forms ('immutable id or stable public vanity id'). It then enumerates the returned content (metadata, locale and voice settings, pronunciation rules), which separates it from list, overview, and localization-summary siblings.

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

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

The description implies the usage context: you have a project id and want the full project details. It does not explicitly state when to prefer this over get_project_localization_summary or show_project_overview, nor any exclusions.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds a genuinely useful behavioral disclosure beyond them: the 100-row cap per content type and that truncated totals are reported as lower bounds. This is exactly the kind of hidden gotcha an agent needs before treating output as authoritative.

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 concise sentences of roughly two dozen words. Purpose is front-loaded in the first sentence and the truncation caveat in the second; every word earns its place, with no filler or restatement of 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?

The output schema documents return values, annotations carry the safety profile, and the schema covers both parameters fully. The description supplies the remaining facts an agent needs — audit scope and truncation semantics — so nothing required for correct selection and invocation is missing.

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

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

Schema description coverage is 100% and both parameters have meaningful descriptions (what a project id may be, the default for expectedDevices). The description adds no parameter-level detail beyond aligning 'rendered-video locales/devices' with expectedDevices contextually, so the baseline 3 for high schema coverage applies.

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

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

The description uses a specific verb ('Audit') with a clear resource ('one Tutorializer project') and detailed scope: configured locales, rendered-video locales/devices, and speech languages. This distinguishes it from siblings like get_project (plain fetch) and show_project_overview (overview, not localization audit) without needing 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?

The word 'Audit' implies a review/completeness-check use case, but the description never states when to prefer this over alternatives like show_project_overview or get_project, and names no exclusion conditions. Selection guidance is left almost entirely to inference.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior and lower the bar. The description adds useful context beyond annotations by specifying that the response includes metadata, full source text, and translation formatted as Markdown. No contradictions or hidden side effects are present.

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 concise sentences, front-loaded with the primary purpose and retrieval method. Every phrase adds information, with no filler or repetition of the title.

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

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

For a simple single-getter with one well-documented parameter, read-only/idempotent annotations, and an output schema, the description is fully sufficient. It even highlights the Markdown formatting detail, leaving no critical gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, and the speechId parameter is already documented as a uuid. The description only restates 'by id' without adding new meaning, so it meets the baseline but adds no further parameter insight.

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 ('Fetch'), a specific resource ('single Tutorializer speech'), and the lookup method ('by id'). This clearly differentiates it from list_speeches and other resource-specific getters like get_project or get_video.

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 implies use when retrieving one speech by its id, and the 'single' wording distinguishes it from list_speeches. It does not explicitly name alternative tools or exclusions, but the context is clear enough for an agent to select it correctly.

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 readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds value by disclosing that the result is a 'bounded preview' and that locale/status belong to videos, not tutorials—facts not visible in annotations or the schema.

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

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

Two sentences with no filler; the primary action and resource are front-loaded, and the second sentence delivers a boundary condition that prevents a common misunderstanding.

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 one-parameter, annotated, read-only tool with an output schema, the description covers the essential behavior and the main data-model caveat. The only small gap is that the 'bounded preview' is not quantified or linked to an alternative way to get full outputs, but this does not block correct invocation.

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

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

The sole parameter is fully documented in the schema as 'Tutorial id (uuid)', so schema coverage is 100%. The description adds no further parameter-level detail beyond confirming the tutorial is identified singularly, which matches the baseline.

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 action ('Fetch one Tutorializer tutorial definition') and a concrete resource, and distinguishes itself from list/get siblings by singular scope and definition-plus-bounded-preview. The caveat about locale/status further clarifies what this resource is not.

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 implies use when a caller needs one tutorial definition rather than a list or a video-specific representation, but it never names alternatives or gives an explicit when-to-use/when-not-to-use rule. The locale/status clarification is useful context, not a routing instruction.

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, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the 'rendered' qualifier and return fields, but does not disclose additional behavioral details such as permissions, availability nuances, or error conditions.

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 a single, front-loaded sentence that states the operation and its scope immediately. The included list of returned metadata is compact and relevant, with no wasted words.

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

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

For a simple single-parameter read tool with full annotations and an output schema, this description is complete. The agent has enough information to call it correctly: the resource, the id parameter, and what the response covers.

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

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

The schema covers the single parameter fully with a description ('Video id (uuid)') and length constraints, so the baseline applies. The tool description adds no meaningful semantic information beyond saying the video is fetched 'by id.'

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 and resource: 'Fetch a single rendered Tutorializer video by id.' It clearly distinguishes this from list_videos and delete_video by emphasizing a single video and a read operation.

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 implies when to use this tool: when you have a known video id and need that video's details. It does not explicitly mention alternatives or exclusions, but the 'single...by id' framing provides clear context without misleading the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the bounded-page behavior, user scoping, and the Markdown return format, which go beyond annotations. It does not describe ordering or default page size, but that is a minor gap given the safety 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?

Two sentences with no redundant wording; the action, scope, and return format are all present. It is appropriately sized and front-loaded.

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

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

The description, annotations, and schema together cover safety, pagination, and return structure. A minor omission is explicit guidance on paginating with cursor, but the schema's cursor description and the phrase 'bounded page' make it sufficient.

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

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

The schema documents cursor but not limit; the description's 'bounded page' weakly implies limit controls page size. It does not explain defaults or how to use cursor for subsequent pages, so it only partially compensates for the 50% schema 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?

The description uses a specific verb ('List') and resource ('Tutorializer projects'), and scopes the operation to the authenticated user's accessible projects and a bounded page. This clearly distinguishes it from sibling tools like list_speeches, list_tutorials, and get_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?

The description clearly implies use when an agent needs a page of projects, but it does not explicitly name alternatives or exclusions. Sibling tool names suggest different resources, but no direct when-to-use vs alternative guidance is provided.

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 cover safety (readOnlyHint, destructiveHint, idempotentHint). The description adds a 'safe preview' and lists the returned fields, which is useful but not extensive. It doesn't contradict annotations and provides a bit of context on behavior, but the bar is lowered by 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 a single concise sentence that front-loads the primary purpose and includes the key filtering and output details without any fluff. Every word contributes to understanding.

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 list tool with pagination and an output schema, the description covers the essential points: bounded page, filters, and preview fields. Pagination mechanics (cursor) are in the schema, and output schema exists, so the description is sufficiently complete. It doesn't explain sorting or default order, but those are not critical for invoking the tool 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 75%, with limit missing a description. The tool description mentions only projectId and language as filters, adding no new information about limit or cursor. The schema already documents most parameters, so the description adds minimal value beyond that.

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

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

The description clearly states the action (list), the resource (speeches), and the scope (bounded page). It distinguishes from the singular get_speech by explicitly mentioning pagination and filtering, making 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?

It provides clear context on when to use it (listing speeches) and mentions optional filters, but does not explicitly state when to use an alternative like get_speech for individual retrieval. The context is clear, but no exclusion is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds concrete behavioral detail: it returns a Markdown table with specific columns and notes that locales/devices live on videos. It does not describe pagination via limit/cursor, but the output schema and parameter schema cover those mechanics.

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

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

Two sentences, front-loaded with the operation and resource, followed by the optional filter and return format. Every sentence adds information; no filler or repetition of the title.

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

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

For a simple read-only list tool, the description covers the operation, optional filter, and return shape, with output schema handling full return details. The only minor gap is not mentioning pagination behavior explicitly, though limit and cursor are present in the schema.

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 67%: projectId and cursor already have descriptions, and the description reinforces projectId's filtering role. limit has no description in the schema, but its name and constraints make its purpose clear; the description does not add further semantics. This is adequate but not exceptional.

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 'List Tutorializer tutorial definitions' with a specific verb and resource. Clearly distinguishes from sibling list tools (list_projects, list_speeches, list_videos) by naming tutorials. The optional projectId filter further clarifies scope.

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 context: this is the tool for enumerating tutorial definitions, optionally scoped by projectId. It does not explicitly name alternatives like get_tutorial for single tutorials, but the list-vs-single distinction is strongly implied by the verb and return format. No exclusions are needed for a read-only list operation.

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 cover the safety profile with readOnlyHint, idempotentHint, and destructiveHint false, so the description does not need to repeat that. It adds useful behavioral context by stating that only rendered videos are returned and that the response is a Markdown table with specific columns, going beyond annotations without contradicting them.

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 tightly packed sentences with no filler: purpose first, then filters, then return format. Every sentence contributes information an agent needs to decide whether and how to call the tool.

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

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

For a simple read-only list tool with an output schema, high schema coverage, and strong annotations, this description supplies the essential filters and response shape. Pagination details are already present in the schema, so nothing critical is missing for correct invocation.

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

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

Schema coverage is 83%, so the schema already documents most parameters. The description names four filter parameters, which adds a slight grouping but mostly restates the schema; limit and cursor are left to the schema, which already describes them adequately. This meets the baseline for high schema 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?

The description opens with a specific verb and resource ('List rendered Tutorializer videos') and names the optional filters, distinguishing it from sibling list_* tools and get_video. The 'rendered' qualifier scopes it to video outputs rather than tutorial metadata, so an agent can tell it apart 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?

It clearly establishes the tool as a list endpoint with optional filters, giving an agent the context to choose it for broad queries. However, it does not explicitly mention sibling tools or state when not to use it, so it stops short of full when-to-use-versus-alternatives 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?

The description adds meaningful behavioral context beyond the annotations: it mentions the ElevenLabs dictionary synchronization and explicitly states that existing speech audio is not regenerated. This goes well beyond the destructiveHint and idempotentHint flags, providing valuable side-effect information without contradiction.

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

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

Two sentences with no filler. The primary action is front-loaded, followed by essential behavioral notes. Every word earns its place, and the structure is ideal for quick agent comprehension.

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 tool is simple, and the description covers the action, side effects, idempotency, and audio regeneration caveat. The schema fully documents parameters, annotations cover destructive/idempotent, and an output schema exists, so nothing critical 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 100% with both parameters already described in the schema (exact word/phrase, project id). The description does not add parameter-specific details, but the baseline of 3 is appropriate given the schema's completeness.

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 ('Remove one project pronunciation rule') and adds the side-effect of synchronizing the ElevenLabs dictionary. It clearly distinguishes itself from the sibling set_pronunciation_rule by describing the inverse action, and its scope 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 implies its use case (removing a rule) and notes idempotency, but does not explicitly contrast it with set_pronunciation_rule or state when not to use it. However, the purpose is clear enough for an agent to infer appropriate usage without further 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?

The description adds valuable behavioral context beyond annotations: it discloses the synchronization side-effect and the idempotent no-op behavior for identical rules. These align with the idempotentHint annotation and enrich the destructiveHint, which alone would not convey the external dictionary sync or idempotency details.

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 extremely concise and front-loaded with the core action. The second sentence adds a critical behavioral note without waste. Every word contributes to understanding the tool's purpose and side effects.

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

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

Given the complexity of a mutation tool with annotations and an output schema, the description covers the essential aspects: the operation, synchronization, and idempotency. It does not explain return values, but the output schema exists. Minor gaps like error handling or prerequisites are acceptable given the schema and annotations.

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?

All four parameters are fully described in the input schema (100% coverage), so the description does not need to add much. It adds the context that a rule is identified by word (implied by 'add or replace'), but this is minor. The baseline of 3 is appropriate because the schema carries the parameter details.

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

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

The description clearly states the tool's action: add or replace a pronunciation rule, and mentions synchronization with the ElevenLabs dictionary. It distinguishes itself from the sibling remove_pronunciation_rule implicitly by focusing on add/replace, but does not explicitly name alternatives, so it is not 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?

The description does not provide explicit guidance on when to use this tool versus the sibling remove_pronunciation_rule or other tools. It implies usage for adding or replacing rules, but no explicit exclusions or alternatives are mentioned, leaving the agent to infer based on tool names 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 destructiveHint=false, so the safety profile is covered. The description adds a mild behavioral cue with 'snapshot' and 'bounded tenant-scoped', but it does not go into specifics about what the snapshot excludes or how counts are computed. No contradiction with 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?

Two sentences, each earning its place: the first states what the tool does, the second states when to use it. No filler or repetition of schema fields.

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 tool is simple (one required parameter), has an output schema, and annotations cover safety. The description gives enough to invoke it correctly. A minor gap is the missing explicit contrast with get_project for full-detail needs, but the count-snapshot framing makes the scope reasonably clear.

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% and the schema description already says 'Tutorializer project id or stable public vanity id to render'. The tool description reinforces this with 'immutable project id or stable public vanity id' but adds no new parameter-level semantics or formatting constraints. 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?

The description names a concrete operation ('Render ... project snapshot') and pins down the content (tutorial, video, and voiceover counts), which clearly differentiates it from list_projects and get_project at the purpose level. 'Bounded tenant-scoped' adds a scope qualifier, though it is somewhat jargon-heavy and does not explicitly name sibling alternatives.

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

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

The description gives clear invocation context: use after listing projects or when an immutable/stable id is already available. It does not explicitly state when not to use the tool or name get_project as the alternative for full project details, but the provided context is unambiguous enough for an agent to select 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 mark destructiveHint and idempotentHint, but the description adds crucial detail beyond those signals: it explains the merge semantics (unspecified fields keep current values), the locale replacement behavior and its effect on the localization audit, and the no-op case. This gives the agent a precise mental model of the tool's side effects.

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, each carrying distinct information: what changes, how the rewrite preserves unspecified fields, and the special destructive/idempotent locale behavior. No filler or redundant wording; the key behavioral details are front-loaded.

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

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

Given an output schema exists, 7 parameters are individually documented, and annotations cover safety and idempotency, the description supplies the remaining operational semantics needed to call the tool correctly: partial update behavior, locale replacement consequences, and no-op conditions. 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?

Schema coverage is 100%, so the baseline is 3. The description adds the important whole-record rewrite behavior, clarifying that omitted parameters are preserved rather than reset. The locale replacement note is redundant with the schema's own parameter description, but the partial-update semantics are genuinely additional value.

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 ('Change') and resource ('Tutorializer project'), and enumerates the exact fields that can be modified: name, domain, locales, default voice or narration speed. This clearly distinguishes it from sibling update tools for speech, tutorial, and video, which target different resource types.

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 strong operational context ('Reads the stored project first and rewrites the whole record') that implies when to use it, but it never explicitly contrasts with create_project or get_project, nor does it state when not to use it. The intended usage is clear from context but left to inference.

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

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

Annotations already flag destructive and idempotent behavior, but the description goes further by explaining the mechanism (re-synthesis with the project's speech provider), the cost (synthesis credits), the consequence (previous audio is replaced), and the no-op case. This adds real behavioral context beyond the annotation flags and does not contradict them.

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 dense sentences: the first states the operation and scope, the second explains side effects and no-op behavior. There is no filler, no repetition of schema content, and the most decision-relevant information is front-loaded.

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 5-parameter tool with an output schema and informative annotations, the description covers all the non-schema knowledge an agent needs: re-synthesis behavior, credit consumption, audio replacement, and the no-op condition. Nothing material is missing for correct invocation.

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

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

The input schema already documents all 5 parameters with descriptions, so schema coverage is 100%. The description adds only a general rule that each listed field determines the audio, which is useful context but does not need to repeat per-parameter details already present in 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?

States a specific action ('Change') and a precise resource ('one Tutorializer voiceover segment'), and enumerates the affected fields: text, translation, language, and voice. This clearly distinguishes it from the sibling update_project/update_tutorial/update_video tools by naming the voiceover segment and its re-synthesis behavior.

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

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

The description makes clear this is for editing an existing voiceover segment rather than creating one, and gives a practical condition: only real field changes trigger re-synthesis while unchanged values are a no-op. It does not explicitly name alternatives like create_speech, but the context is unambiguous enough for an agent to select the tool correctly.

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 description provides meaningful behavioral detail beyond the annotations: it reads the stored tutorial first, rewrites the whole record, preserves unspecified fields, and treats submitting unchanged values as a no-op. This aligns with idempotentHint=true and explains the destructiveHint=true 'rewrite' behavior without contradicting any annotation.

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 with no fluff: the first states the operation, the second explains the read-before-write behavior, the third clarifies idempotency. Every sentence earns its place and the key purpose is front-loaded.

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

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

Given a simple 3-parameter schema, an output schema, and annotations, the description covers the essential behavioral contract completely. There is no need to explain return values because an output schema exists, and the partial-update semantics are fully disclosed.

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

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

The schema already covers all three parameters with clear descriptions, so the baseline is 3. The description adds valuable context that unspecified fields retain current values, directly informing how optional name and defaultVoice parameters behave.

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 explicitly states the tool renames a tutorial or changes its default voice, naming a specific resource (Tutorializer tutorial) and the two supported update operations. This clearly distinguishes update_tutorial from sibling tools like update_project, update_speech, and update_video.

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

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

The description gives clear context for when to use this tool: updating an existing tutorial's name or default voice, with partial-update semantics via read-before-write. It does not explicitly name alternatives or state when not to use it, but the resource-specific wording makes the usage context sufficiently clear.

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 (destructiveHint=true, idempotentHint=true, readOnlyHint=false), the description adds the key behavioral detail that it reads the record first and rewrites the entire document. It also clarifies the idempotent nature by stating unchanged values are a no-op. This goes beyond what annotations alone convey.

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

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

Two sentences, front-loaded with the purpose, then the behavioral nuance. Every sentence carries value; there is no filler or repetition of schema details.

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

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

Given the presence of an output schema and annotations that already convey destructive and idempotent hints, the description adds the crucial read-modify-write context and no-op clarification. It does not explain return values, but the output schema likely covers that. It is complete enough for an agent to call it correctly.

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

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

Schema description coverage is only 17% (only videoId and url have descriptions). The description lists example fields ('locale, device, dimensions or media URLs'), which covers several parameters but not all (e.g., format, duration, fileSize). It partially compensates for the low schema coverage but is not exhaustive.

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 ('Correct'), a precise resource ('one registered Tutorializer rendered video'), and names example fields ('locale, device, dimensions or media URLs'). It clearly distinguishes from sibling update tools for other entities (e.g., update_tutorial, update_speech) because it is scoped to videos.

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 explains the read-modify-write behavior, which is critical for safe usage: it reads the stored record first and rewrites the whole document, so unspecified fields retain their values. It also notes that submitting unchanged values is a no-op. It does not explicitly name alternatives or when not to use it, but the tool's purpose is clear enough given the sibling set.

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