The Scribble Thing

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

Annotations already supply idempotentHint, readOnlyHint, and destructiveHint, so the safety profile is covered. The description adds 'asynchronous,' which is a meaningful operational trait, but it does not disclose the job lifecycle, required terms acceptance, or what the caller should do after submission. 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 a single front-loaded sentence with no filler or redundancy. It earns its place, though it is very brief relative to the complexity of the tool. Structure is clean and immediately scannable.

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 10 parameters, 6 required, multiple legal-acceptance flags, and asynchronous behavior, this description is incomplete. It does not mention that accept_terms, accept_retention, and accepted_terms_version are mandatory, nor does it explain how to use idempotency_key or check the resulting animation via sibling get tools. The output schema may cover return values, but the operational context is still insufficient.

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 10%, so the description bears heavy responsibility for explaining parameters. It adds minimal semantic value by indicating the image should be base64-encoded line art, but it says nothing about speed, show_hand, order_text, idempotency_key, installation_id, or the required consent/terms parameters.

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: 'Create an asynchronous animation from a base64-encoded line-art image.' It clearly names the action and input format, and the word 'Create' distinguishes it from the sibling get/delete/download tools. This is immediately clear and not a tautology.

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 by the verb 'Create' and the presence of sibling tools like get_scribe_animation and delete_scribe_animation. There is no explicit statement of when to use this tool versus alternatives, no exclusion criteria, and no mention of prerequisite steps such as accepting terms.

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 useful behavioral context beyond the annotations: 'Immediately' implies the deletion is synchronous, and 'all of its stored files' clarifies the destructive scope. This complements the existing destructiveHint and readOnlyHint 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?

The description is a single, front-loaded sentence with no filler. Every word contributes to the core meaning: immediate action, object targeted, and full scope of deletion.

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 two-parameter tool with an output schema and strong annotations, the description covers the destructive scope well. Still, it leaves the role of access_token and the request semantics for animation_id entirely to inference, so it is not fully complete.

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 compensate by explaining the parameters. It only vaguely relates to animation_id through 'one animation session' but gives no meaning to access_token, nor does it explain how the parameters are used in the deletion operation.

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 ('delete'), a specific resource ('one animation session'), and a clear scope ('all of its stored files'). It clearly distinguishes this tool from the sibling create/get/download tools, leaving no ambiguity about its function.

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 usage: call this when the intended action is to remove an existing animation session and its files. However, it does not explicitly state when to use this over alternatives or mention any prerequisites, though there is no sibling deletion tool to contrast with.

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, open-world, and non-destructive behavior. The description adds value by specifying the breadth of information returned ('current limits, terms, retention, pricing, and integration URLs'), clarifying what the agent can expect beyond a generic 'service info' label.

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 lists the distinct information categories with no filler or redundancy. Every word contributes meaning, and the structure makes scanning easy.

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 zero parameters, an output schema that handles return values, and no overlapping sibling tools, the description is fully sufficient. It names the exact scope of the service information, leaving no obvious operational gap.

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 has zero parameters, which sets the baseline at 4. There is nothing the description needs to explain about input semantics; the empty schema already confirms no arguments are required.

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 ('Get') and resource ('Scribble service info'), then enumerates the exact content domains: limits, terms, retention, pricing, and integration URLs. This clearly differentiates it from the sibling animation-management tools.

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

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

The context makes the use case obvious: this is the only service-info tool among animation-focused siblings, so there is no ambiguity about when to call it. It does not explicitly name alternatives or exclusions, but none are needed given the unique purpose.

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. The description adds useful behavioral context by explaining that repeated polling is expected and that the animation has terminal states (completes or fails). It also scopes the operation to 'private' animations, which clarifies access_token usage.

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 one concise sentence with no redundant words. It front-loads the core action ('Poll') and packs the key behavior and scope into a compact statement.

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 two-parameter polling tool with a dedicated output schema, this description is largely sufficient. The main gap is the lack of explicit parameter guidance, but annotations and schema cover safety, idempotency, and required fields, and the description conveys the polling lifecycle clearly enough.

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 compensate by explaining the parameters. It implies animation_id is the polled resource and 'private' suggests access_token is needed, but it never explicitly maps either parameter to its role or format. Without this, the agent must infer parameter meaning 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?

The description states a specific action ('Poll'), a clear resource ('one private animation'), and the termination condition ('until it completes or fails'). It is easily distinguished from siblings like create_scribe_animation, delete_scribe_animation, and get_scribe_animation_download.

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 polling framing clearly signals this is for checking the status of an animation after creation, not for creating, deleting, downloading, or managing the service. It does not explicitly mention when not to use it, but the narrow scope and sibling names make the intended usage evident.

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, so the operation is clearly non-destructive. The description adds value by revealing that the URL is short-lived and only available for completed videos. This does not contradict 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?

A single, focused sentence communicates the core purpose and key constraint without wasted words. The most important information, short-lived URL and completed video requirement, 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?

The output schema exists, so the return value does not need explanation. Annotations cover the safety and idempotency profile. The description gives the essential behavioral constraint and target kind. It is slightly incomplete in not providing explicit routing against sibling tools, but for a simple 3-parameter operation this is a minor omission.

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 compensate. It adds meaning to the kind parameter by associating it with preview versus clean video, but it does not explicitly explain animation_id or access_token. These parameter names are fairly self-explanatory, but the coverage gap is only partially addressed.

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 identifies the operation: generating a short-lived download URL, and specifies the resource (completed preview or clean video). It distinguishes this from siblings like get_scribe_animation by focusing on the URL generation rather than animation retrieval or management.

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 usage after an animation is completed and for either preview or clean video, giving some context. However, it does not explicitly state when to prefer this over alternatives like get_scribe_animation, nor does it mention exclusions or preconditions beyond completion.

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, readOnlyHint=false, and idempotentHint=false, lowering the bar. The description adds useful behavioral context by stating the code is 'single-use' and is 'consumed', which makes the irreversible nature explicit and 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?

A single sentence with no filler; the core action and effect are front-loaded. Every phrase adds meaning, despite the larger parameter-documentation gaps penalized elsewhere.

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 tool with three required parameters and no schema-level parameter descriptions, the description is too sparse. It does not explain access_token or animation_id, state prerequisites, or describe error/expired-code behavior, though an output schema partially mitigates return-value questions.

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?

Input schema has 0% description coverage, so the description must carry parameter meaning. It only clarifies that unlock_code is user-supplied and single-use; animation_id and access_token remain unexplained in both schema and description, leaving a substantial 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 action ('Consume'), a specific resource ('a user-supplied single-use code'), and the outcome ('unlock one clean video'), which clearly sets it apart from the sibling create/delete/get tools. It is not a tautology and conveys a distinct purpose.

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?

No guidance is provided about when to redeem a code versus using sibling tools, nor are any preconditions or exclusions mentioned. The only implicit context is that a user supplies a code, but the description does not help an agent decide between alternatives.

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