Scribiz

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

Annotations only cover the safety profile (readOnly, openWorld, non-idempotent, non-destructive); the description adds substantial behavior beyond them: the cost model (0.1 min plus first-time video reading), the async contract ('status processing' + job_id -> call get_job), the answer trust caveat (verify cited moments), and that the output is wrapped as untrusted video text. These are exactly the operational traits 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?

Dense but front-loaded: purpose, routing guidance, cost, trust, async handling, and tier limits in a tight sequence. Given the tool's complexity, the length is justified, though it is near the upper bound of what one definition should carry.

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?

Although an output schema exists, the description still explains the shape of the answer (3-5 cited moments with timestamps/links) and covers the async continuation path, cost, and no-API-key degradation. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the 'watch' parameter's no-API-key behavior, but that detail already lives in the schema; it adds little per-parameter meaning beyond what the structured fields provide.

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 ('ask a question about one video and get an answer with 3 to 5 cited moments'), and explicitly distinguishes itself from search_video by contrasting whole-video/topic questions with exact word/phrase lookup. An agent can route between ask_video and search_video 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?

Gives explicit when-to-use ('questions about the whole video or a topic across it, and for what was said') and when-not, naming the cheaper alternative: 'To find where a word or phrase is said, search_video is cheaper and exact.' It also flags the API-key tier limitation and the 5-questions-per-day cap.

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 establish read-only, idempotent, non-destructive semantics, and the description adds the traits annotations cannot express: the tool blocks up to the server's wait time, job ids are private to the caller and expire after 30 minutes, retry_after_seconds signals a still-running job, and results are cached so the recovery call is fast.

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?

Five short sentences, each carrying distinct operational information, with the purpose and the precondition front-loaded. No filler and no repetition of 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?

An output schema exists, yet the description still characterizes the two possible returns (processing plus retry_after_seconds, or the original tool's exact payload) and the 30-minute retention window. For a one-parameter polling tool, nothing an agent needs to invoke or interpret 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?

Schema coverage is 100% and the parameter is already documented as the job_id from a processing answer, so the baseline is 3. The description reinforces the one genuinely error-prone aspect ('copy all of it', it can be long), which adds a little value without contradicting the schema's length bounds.

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 ('Check a video run') and scopes it to runs that returned status "processing", which instantly separates it from the sibling tools ask_video, search_video, and get_transcript. It also makes the relationship to the originating call explicit by promising the same return payload.

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 unambiguous when-to-use ('a video run that returned status processing') and covers both non-terminal branches: still running, retry with retry_after_seconds; unknown or expired, repeat the original call instead. No inference is left to 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 only cover the read-only/idempotent safety profile; the description adds the operational traits that actually matter here: pagination via nextCursor, a default page size with a token estimate, possible latency with a 'processing' status and job_id, credit costs per transcript vs free cached/stored reads, and that missing captions never trigger a media fallback. It also discloses the auth requirement and the differing behavior for YouTube vs other links. This is well beyond what the annotations provide.

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 routing decision before any parameter detail, which is the right order. The final paragraph is a dense wall of billing, auth and fallback caveats that is useful but longer than strictly necessary, and a few clauses restate 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?

For a 10-parameter, open-world, long-running tool, the description covers the decisions an agent must make: auth prerequisites, credit cost, latency and job handling, pagination continuation, and untrusted-text wrapping. With an output schema present it correctly does not spend words on the return shape.

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, but the description adds value the schema lacks: the '~15k tokens' framing for max_chars, the requirement that the cursor be used with identical arguments, and the behavioral caveat that speakers is ignored without an API key. Some entries (from/to formats, pauses, format enum) largely restate 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 verb and resource ('Read the transcript of a video') and immediately scopes it with 'one page at a time'. It also names the siblings it is not (ask_video, search_video), so an agent can route correctly 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?

Explicit when-to-use ('only when you need the words themselves (quote, translate, copy, review)') and when-not ('To answer a question or find where something is said, use ask_video or search_video first'), with the reason given ('they cost far fewer tokens'). Alternatives and the selecting condition are both 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, yet the description layers on real operational context: first read uses captions or a model reading the link, subsequent reads are cached and free, async processing surfaces a job_id requiring get_job, output is wrapped as untrusted video text, and no API key means no on-screen notes with approximate timestamps on model-read links. That is substantive disclosure well beyond the annotation set.

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 leading sentence front-loads the essential 'start here' guidance, and each subsequent sentence carries non-obvious information about caching, async handling, or tier limits. It is dense to the point of being one long block, and a few clauses (token counts, include defaults) overlap the schema, but 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?

With an output schema present, return values need not be re-explained, and the description correctly focuses on what the schema cannot convey: entry-point role, detail/include defaults, auth-dependent omissions, async job handoff, and timestamp reliability caveats. An agent has everything needed to call this correctly on the first try.

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, but the description adds behavioral meaning: the 'brief' default is quantified at ~2,000 tokens, 'transcript' in include returns only its first page, and 'watch' is inert without an API key. These clarify the practical effect of the parameters rather than merely restating enum values.

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 ('Returns an overview you can reason from without reading the transcript') and enumerates exactly what comes back: title, length, language, summary, chapters with timestamps, key moments with links. It also positions itself against siblings by declaring that the transcript is never part of the default and pointing to get_transcript for it.

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?

'Start here for any video' gives an explicit entry-point rule, and the description routes to alternatives by name: get_transcript for continued transcript pagination and get_job when the initial read returns status 'processing' with a job_id. Both the trigger and the escalation paths are spelled out, leaving nothing 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 readOnly/idempotent/non-destructive/openWorld, yet the description adds substantial behavioral context beyond them: it is a local keyword search with no model call and no extra billed minutes after the first read, results are wrapped as untrusted video text, an API key is needed for YouTube links, on-screen notes are skipped without a key, and model-read timestamps can be up to a minute off. This is exactly the extra layer annotations cannot express.

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 purpose and value, then constraints and edge cases. Dense but every clause carries information; length is driven by the tool's genuine complexity (auth, job status, approximate timings). Slightly packed, with several parenthetical asides, but 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, and the description still covers everything else an agent needs: matching semantics, ranges, defaults, the untrusted-text wrapping, the processing/job_id path, and the no-API-key behavior for YouTube links. Complete for a 6-parameter search tool with this complexity.

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 documents url, query, from/to, limit and language. The description nonetheless adds genuinely useful semantics: the query matches words (with plural/tense variants) rather than meaning, limit spans 1–20 with a default of 8, and from/to constrain the search to a portion of the video. This exceeds the baseline 3 by clarifying matching behavior the schema does not capture.

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 precise verb and resource — ranked moments with timestamps and links located within a video — and enumerates the sources searched (transcript, on-screen notes, chapters, key moments). It explicitly contrasts itself with get_transcript and ask_video, so an agent can pick it out among siblings 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?

Gives explicit when-to-use guidance ('Use it before get_transcript on any video longer than about ten minutes'), names the alternative for semantic queries ('or call ask_video'), and specifies the fallback path when a job is still processing (call get_job). Exclusions and alternatives are both present.

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