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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial non-structured context: no credit spend, no job creation, concrete failure modes (private, removed, region-locked, audio-only, too large), local-file limitation, and a realistic latency range of 2-15s with occasional 45s spikes.

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 purpose, then usage, platforms, and returns in a logical order; every sentence carries information. Slight redundancy in repeating the platform list both as support and as failure context, and it is longer than strictly necessary.

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?

Even though an output schema exists, the description usefully explains the failure semantics (reason enum values audio_only/too_large/unavailable) and the null-duration case for direct links, which is exactly what an agent needs to interpret results. Nothing material is missing.

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

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

Schema description coverage is 100% and the single parameter is fully described there, including the same platform list. The description restates but does not extend the parameter contract, so the baseline 3 applies.

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

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

The first sentence states a specific verb (checks), resource (video link) and the exact return payload (title, length, platform), plus a scoping constraint (spends no credits, creates no job). It is clearly distinguishable from quote_clip_job and get_clip_job, which are named directly.

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 ('is this link usable?', 'how long is this video?'), when-not ('Do not use it for existing jobs; use get_clip_job instead'), and the alternative for pricing ('call quote_clip_job directly: it runs the same check'). This is close to ideal routing 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?

Goes well past the annotations: it discloses cost ('Free: spends no credits'), the one-article-per-video-per-account constraint with re-call behavior returning the existing article, that failed articles cannot be regenerated via the API, and the 1-3 minute latency. These are exactly the side-effect and lifecycle facts an agent needs beyond idempotentHint/destructiveHint.

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 capability, then the output inventory, cost, prerequisites, uniqueness rule and next step. Dense but every sentence carries distinct information; the long enumeration of article fields is the only mildly excessive part given an output schema exists.

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 names the key return fields (article_id, status, source clip job) and gives the timing and follow-up call. Combined with the failure and idempotency rules, an agent has everything required to invoke 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 coverage is 100%, so the schema already documents the single clip_job_id parameter, making 3 the baseline. The description adds meaning beyond the schema by requiring the job be 'completed' and by explaining that any clip job of the same source video resolves to the same article, which affects how the parameter should be chosen.

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 ('turns the source video of a completed clip job into a long-form article') and enumerates exactly what the article contains. It is clearly distinguishable from siblings like get_article (retrieval) and create_clip_job (prerequisite).

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 about when to use it ('blog posts, show notes, chapter lists or the full transcript of a video that has already been clipped'), the prerequisite ('needs a clip job with status completed, create one with create_clip_job first'), and the follow-up ('call get_article with wait_sec=50'). No ambiguity about routing.

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

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

Goes well past the annotations: exact pricing model (1 credit per started minute, minimum 1, charged at creation), the 30-minute-per-job cap with start_sec/end_sec as the split mechanism, no-cancellation, the max_credits refusal behavior, the dedupe-within-10-minutes rule, the async lifecycle (job_id returned with status queued, poll get_clip_job with wait_sec=50), and the no-automatic-refund failure path. The annotation set (destructive/non-idempotent/openWorld) is consistent with this, and the dedupe nuance is stated as a bounded exception rather than a 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?

Long, but proportionate to a 23-parameter, credit-spending, non-cancellable job creator. It is front-loaded with the spend warning, then preflight, then routing, then key parameters, then return/polling behavior — each block is distinct and no sentence is 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?

Covers everything an agent needs to call this safely: required preflight, cost, hard caps, dedupe rules, required parameters, the follow-up polling call with a concrete wait_sec, and failure/retention handling. An output schema exists, so the description is not obliged to explain the response body, and it correctly limits itself to noting job_id/status.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real orientation on top: it flags which parameters matter (source_url, start_sec/end_sec, video_mode, clip_length, caption_style, language, prompt), states that local files are unsupported, explains the 30-minute range constraint that motivates splitting, and routes enum-heavy parameters to get_options_guide. It stops short of describing every one of the 23 options, which is defensible given 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?

Opens with a specific verb+resource ('Starts AI clipping of a long video into vertical 9:16 short clips') and enumerates the concrete output features (captions, hook title, cold-open, music, B-roll). An agent can distinguish it from create_transcription, recut_clip_job and retry_clip_job immediately, since those are named as the wrong tools for adjacent needs.

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 (podcast, stream, interview, lecture, vlog → Shorts/Reels/TikTok), explicit when-not with the correct alternative for each case (create_transcription, recut_clip_job, retry_clip_job), a mandatory preflight ('run quote_clip_job, show the price... get explicit agreement'), and the 10-minute duplicate window with allow_duplicate as the escape hatch.

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

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

Adds substantial behavior beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it discloses cost ('Free: spends no credits'), the accepted source platforms, the async contract ('Returns transcription_id right away'), expected latency (1-5 minutes), and the follow-up call with wait_sec=50. This is far richer than the structured hints alone.

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

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

Front-loaded with purpose and cost, then links, then usage routing, then the parameter note, then the async return contract. Every sentence carries distinct information (cost, platforms, exclusion, alternative, polling step) with no filler.

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

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

For a two-parameter async creation tool with a full output schema and annotations, the description supplies everything an agent needs: what it does, when to prefer alternatives, input constraints, cost, latency, and the exact next call. Nothing material is missing.

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

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

Schema coverage is 100% and the description largely echoes the schema's own language guidance (two-letter code, omit to auto-detect), so it earns the baseline-3-and-up territory. It adds real value with the constraint that auto-detect yields 'one language for the whole recording', which the schema does not state.

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 ('starts a timed speech-to-text transcription of a video or audio link') and clearly distinguishes itself from siblings: it names create_clip_job for supported links and create_article as the alternative when a clip job already exists. An agent can tell this apart from create_clip_job and create_article 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 ('when the user needs the text, subtitles (SRT) or timestamps of a video without making clips') plus a named alternative with its selecting condition (create_article for videos with a completed clip job), and an explicit exclusion (local files not supported). Nothing is 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 only cover safety profile; the description adds the async contract (returns thumbnail_job_id immediately, finishes in 1-2 minutes), the cost model (free, no credits, but each variant is a separate generation), and the required follow-up call. This is exactly the context annotations cannot carry.

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

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

Front-loads purpose, then a behavior note, then parameters, then the async flow. Slight redundancy between the parameter list in prose and the schema's own descriptions costs it a point, but overall tight and well ordered.

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 detailed; the description still supplies the essential async lifecycle, cost behavior and the follow-up tool. Everything an agent needs to invoke and then poll correctly is present.

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 already documents types, enums, defaults and length limits. The description reinforces the required params (source_url, language) and mentions constraints, but adds no syntax or semantics beyond the schema. Baseline 3 is correct.

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 ('Generates 1 to 4 AI YouTube thumbnail images') with resolution, format and inputs, and names the companion retrieval tool get_youtube_thumbnails. An agent can distinguish it from siblings like create_clip_job or create_article 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?

Explains when to request multiple variants ('ask for more than one only when the user wants options') and gives the explicit follow-up call pattern with wait_sec=50. It lacks explicit when-not-to-use framing against other image/clip tools, so not a perfect 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds traits they cannot express: it is free, works without a key, changes nothing, and the credit balance is deliberately unavailable via the API (surfaced on the web instead). That last point is a genuinely useful boundary an agent would otherwise guess wrong about.

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

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

Purpose is front-loaded in the first sentence, followed by usage guidance and return details. The third paragraph enumerates every returned field, which is somewhat long given an output schema exists, but it remains scannable and each sentence carries information.

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

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

A zero-parameter diagnostic with a declared output schema is fully covered: the agent knows what it does, when to call it, that it is safe and key-free, and what limitations to expect regarding credit balance.

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?

Zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly avoids inventing inputs.

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: checks whether the configured MnogoReels API key works and reports server settings. It is unmistakably distinct from every sibling, all of which deal with clips, assets, packs, transcriptions or articles.

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

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

Gives an explicit trigger: 'Use it first when other tools fail with an authentication error, or when the user asks which account or mode is active.' Both a diagnostic and an informational use case are named, 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 declare readOnly/idempotent/non-destructive, yet the description adds substantial behavioral context: that the call can block while waiting, that progress notifications are emitted, that images_pending text is final and will not change, and that failed images cannot be retried through this server. It also flags the untrusted_source_text wrapping, which is critical safety context 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?

Content is front-loaded with purpose, then waiting, then paging, then return details. Four short paragraphs are slightly longer than strictly necessary and some return-field detail overlaps the output schema, but each sentence conveys real operational information.

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

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

For a polling-and-paging read tool, the description covers job states, truncation/pagination, waiting semantics, partial-image behavior, and the untrusted-content boundary. With an output schema present it need not document return fields, yet the extra polling and safety context makes the definition complete 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 100%, so the baseline is 3, but the description adds genuine meaning beyond the raw schema: wait_sec is explained as blocking inside the call, include_transcript is described as appending the full timed transcript, and offset is tied to the next_offset pagination token. It does not clarify max_chars behavior beyond the schema.

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

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

The first sentence gives a specific verb (Returns), resource (an article created with create_article), format (Markdown) and accompanying state (its status). The agent can immediately distinguish this retrieval tool from its write sibling create_article and the other get_* 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?

It clearly frames the polling workflow (wait_sec waits inside the call for the text to be ready) and the paging workflow (when truncated is true, call again with offset set to next_offset). It stops short of explicitly naming when to prefer a different sibling or a when-not condition, but the context for use is unambiguous.

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 read-only/idempotent safety profile, and the description adds substantially beyond them: the API key requirement, the 15-minute expiry of catalog=mine links and the links_expire_in_sec field, divergent return shapes per catalog, the fact that shared items are downloaded off-site, and that provider text is wrapped in <untrusted_source_text>. This is unusually rich operational detail an agent needs to sequence calls correctly.

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 action and the key routing decision in the first sentence, then the catalog-specific return details. Dense but every sentence carries information; it is slightly longer than strictly necessary because the return-value details duplicate the output 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?

Given the presence of an output schema, the description need not explain returns, yet it still clarifies the divergent shapes per catalog plus the expiry semantics and untrusted-text handling. Everything an agent needs to call this correctly and interpret the result is present.

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 both parameters are already documented in the schema. The description's constraint that 'catalog must be the catalog the asset_id came from' reinforces the pairing but largely restates the schema's own wording, adding no new syntax or format information. Baseline 3 is appropriate when the schema carries the load.

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 one B-roll item by asset_id with fresh links') and immediately distinguishes itself from the sibling search_broll, which is a finder rather than a fetcher. An agent can tell exactly what this does without opening the schema.

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

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

Gives an explicit when-to-use rule ('right before downloading an item found with search_broll'), the reason (catalog=mine links expire after 15 minutes), and an explicit when-not-to-use routing ('to find items use search_broll instead'). This is the full when/when-not/alternative triad.

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, yet the description still adds substantial behavior beyond them: the call is 'free', progress notifications are emitted while waiting, partial results are limited to a ready-clip count unless include_partial_clips=true, failed jobs can revert to queued on automatic retry, media_available=false signals storage retention (30 days on free plan), and returned text is wrapped in <untrusted_source_text>.

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, then wait/polling behavior, then return shape, then edge-case Notes. Dense but every paragraph carries distinct operational information; the main cost is re-stating wait_sec's default and max that the schema already declares.

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 polling tool with an output schema, the description covers invocation (wait_sec, include_partial_clips), result shaping (max_clips, response_format), failure/retry states, retention limits, and prompt-injection handling. Nothing an agent needs to call or interpret this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema only states per-field: the max_clips ceiling drops from 30 to 10 when response_format=detailed, and wait_sec's timeout/notification behavior is expanded. It is genuinely additive rather than redundant.

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 the status, progress and results of a clip job') and immediately grounds it in the sibling tools that produce such jobs (create_clip_job, recut_clip_job). An agent can distinguish this from list_clip_jobs 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 concrete operating guidance: wait_sec polling semantics, wait_sec=0 for an instant snapshot, and the recommendation to tell the user rather than poll continuously when eta_seconds exceeds 600. It also routes to list_clip_jobs for job-id discovery. It does not explicitly state when NOT to use this tool, so it falls just short of the top band.

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 openWorldHint=false, so the safety profile is covered. The description still adds genuinely useful context beyond them: free, no API key required, makes no network calls, and the 30-minute limit per job. It stops short of describing the shape of an individual section's output, but the output schema covers that.

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

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

Two tight paragraphs: the first says what it covers plus operational facts, the second says when to use it and how to parameterize. No sentence is filler and the key constraint (free, no key) 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 zero-required-parameter reference tool with an output schema, the description supplies everything an agent needs: coverage scope, trigger conditions, parameter behavior, and the cost/auth profile. 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% and the enum self-documents the section names, so the baseline is 3. The description adds real meaning on top by explaining what the values do ('topic selects one section; all returns everything'), which resolves the ambiguity of the 'all' default.

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 ('Explains') and resource ('the option values accepted by create_clip_job and recut_clip_job'), then enumerates the domains covered (video modes, caption styles, pricing, etc.). An agent can distinguish this reference tool from the sibling job-creation tools without opening the schema.

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

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

'Use it when the user asks what a style looks like, which mode fits their video, or how much processing costs' gives concrete trigger conditions, and naming create_clip_job/recut_clip_job as the consumers clarifies the relationship to alternatives. The 'topic selects one section; all returns everything' line completes the 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description still adds two things annotations cannot: the call is free (cost), and generated text is wrapped in <untrusted_source_text> tags, which is a meaningful prompt-injection signal. It also describes the offset/next_offset paging loop, though it omits page-size defaults and limits that the schema carries.

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 dense sentences with no filler; the payload contents lead, and follow-up routing comes after. 'Read-only and free' partially duplicates the readOnlyHint annotation, but the rest 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, so return values need not be documented, yet the description still names the major fields; combined with the untrusted-text warning and the paging/follow-up guidance, an agent has everything needed to call this 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 the baseline is 3. The description goes slightly beyond by explaining the transcript paging flow (offset plus next_offset) and the purpose of include_transcript, tying the parameters to a workflow rather than restating their types.

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 one publication pack') and enumerates the payload an agent gets back: titles, descriptions, cover texts, hashtags, thumbnails, teaser videos, article id, clip job id. It is clearly distinguishable from the sibling list_packs, which only enumerates packs.

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 routes follow-up work explicitly: 'Use get_clip_job with clip_job_id for the clips and get_article with article_id for the article,' and tells the agent to set include_transcript=true when the transcript is needed. It does not spell out when to prefer this over list_packs or other retrieval siblings, so it falls short of a full when/when-not statement.

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

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

Adds substantial context beyond the annotations: the call is 'free,' waiting happens in-call with progress notifications, transcripts are paginated and how to continue, and the result is wrapped in <untrusted_source_text> tags (a prompt-injection warning). Annotations only cover the read-only/idempotent safety profile, so this is genuinely additive.

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

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

Three short paragraphs, front-loaded with the core purpose and payload, then polling/format, then return shape. Slight redundancy with format descriptions already in the schema, but every part is relevant.

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?

Despite an output schema existing, the description sketches status values, pagination fields and the untrusted-source framing, so an agent knows exactly how to drive the polling/pagination loop and how to treat the returned text.

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 input schema already documents format values, wait_sec defaults/max and notifications, offset/next_offset, and max_chars bounds. The description largely restates these, so it meets the baseline without extending 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?

States a specific verb and resource and ties it explicitly to its sibling: 'the status and text of a transcription started with create_transcription.' An agent can immediately place it in the create/get lifecycle without reading the schema.

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

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

Gives clear operational guidance: wait_sec polls in-call with progress notifications, and when truncated is true you re-call with offset=next_offset. It doesn't name an alternative tool or state when not to use it, but the create_transcription linkage supplies context.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond that: API key requirement, no job listing, in-call blocking up to 50s with progress notifications, and partial-failure behavior (failed variants don't suppress the rest). Behavioral traits beyond annotations are well disclosed.

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

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

Front-loads the core purpose, then constraints, then parameter behavior, then return shape. Every sentence earns its place with no repetition of the name or 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?

With an output schema present, the description needn't document return fields, yet it helpfully summarizes status, stage, progress_percent and variants. Combined with prerequisite, auth, and partial-failure notes, an 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 already 100%, but the description reinforces wait_sec's semantics (default 30, max 50, 0 = snapshot, progress notifications) and explains why thumbnail_job_id matters (jobs can't be listed). This adds meaning beyond the schema despite the schema already being complete.

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 (returns status and images of a thumbnail job) and explicitly ties it to its sibling create_youtube_thumbnails, making the pair unambiguous. An agent can immediately distinguish it from the create sibling and other get_* 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?

Explicitly names the required prerequisite (keep thumbnail_job_id from create_youtube_thumbnails), notes jobs cannot be listed, and explains the wait_sec tradeoff (0 = snapshot vs default wait). This is a clear when/how-to-use contract with no inference required.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-structured behavior: 'free', ordering is newest-first because the API provides no creation dates, and next_offset is null on the last page. It doesn't discuss rate limits or auth requirements, but for a read-only listing the disclosed traits are solid.

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

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

Front-loaded with the core action and scope, then usage, then pagination semantics, then return shape. The final paragraph enumerating return fields is largely redundant with the output schema, which costs a point, but the rest is dense and waste-free.

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?

Covers purpose, usage, filtering semantics, pagination edge case, and ordering rationale. With an output schema present, the description needn't explain return values yet does so anyway; nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains created_via=api restricts to API-key-created jobs (the schema says 'this server or scripts'), documents limit's 1-50 range with default, and clarifies that next_offset from a page feeds offset. This is real added value over the field descriptions.

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 ('Lists the user's clip jobs'), adds scope ('newest first, including jobs started on the MnogoReels website'), and explicitly names the sibling it differs from ('Use get_clip_job for the clips of one job'). An agent can distinguish it from the many other clip-related 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 three concrete use cases ('find a job_id, see what is still processing, or pick recent results to review') and routes to the alternative tool (get_clip_job) for a different need. Both when-to-use and when-to-use-something-else are present.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: newest-first ordering, cost ('free'), creation restriction, pagination behavior, and a summary of returned fields. It stops short of rate limits or failure behavior, so a 4 is appropriate.

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 front-loaded with the core purpose and then layers in useful context (pack definition, pagination, returns, next steps). It is slightly verbose for a simple list tool—the pack definition and return-field summary could be trimmed—but each sentence contributes context that aids correct invocation.

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 tool's simplicity, rich annotations, and existing output schema, the description is complete enough: it defines the resource, explains pagination, summarizes returned fields, and routes the agent to get_pack and get_clip_job for follow-up. Nothing an agent needs in order to call 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 description coverage is 100%, so both limit and offset are already fully documented in the schema. The description repeats the pagination model ('Pages with limit (1 to 50, default 10) and offset') but adds no new syntax or edge-case meaning beyond what the schema provides, matching the baseline for high-coverage schemas.

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 ('Lists the user's publication packs') and immediately clarifies ordering ('newest first'). It also differentiates from the sibling get_pack by stating that get_pack is for titles, hashtags, thumbnails and teasers, so an agent can distinguish the two tools without opening their schemas.

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

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

It gives explicit context: read-only and free, packs cannot be created through the API, and pagination via limit/offset. It also names alternatives and next steps ('use it with get_clip_job', 'Next, call get_pack for titles...'), making the when-to-use and when-to-continue behavior 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 cover the read-only/idempotent/no-destructive profile, but the description adds substantial behavioral context beyond them: the pricing formula (1 credit per started minute, minimum 1), that options like caption style/hooks/B-roll do not affect price, the 30-minute job cap, and the upper-bound case where credits_exact is false because the API does not reveal a recut's original range.

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 key value proposition ('without spending anything', 'Free and read-only') and organized into pricing/usage/return paragraphs. It is dense and slightly long, with a few return-value details that partly overlap the output schema, but almost every sentence carries actionable information.

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

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

For a pre-flight quoting tool this is complete: it covers when to use it, the cost model, the interaction between job_id and the range parameters, the credit-exactness caveat, and the failure mode for unmeasurable direct links. The output schema exists, so return-value enumeration is a minor redundancy rather than a 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?

Schema coverage is 100%, so the baseline is 3, but the description genuinely extends semantic meaning: it explains that a recut without start_sec/end_sec reuses the original job's range and yields an upper-bound quote, that omitting both defaults to the whole video (requiring a length lookup), and that the 30-minute cap forces splitting long videos.

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 ('Calculates the credit cost') and explicitly names the sibling operations it prices (create_clip_job, recut_clip_job) while distinguishing itself as a no-cost simulation. An agent can tell this apart from create_clip_job/recut_clip_job 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 routing: pass source_url to price a new video, job_id to price a recut, and states the prerequisite workflow ('Show the credits to the user and get their agreement before calling create_clip_job or recut_clip_job with max_credits of at least this amount'). It also notes a fallback when the length cannot be determined.

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

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

Annotations declare destructiveHint=true and non-idempotent, and the description goes well beyond them: exact credit cost (1 per started minute, min 1, max 30), that the original job/clips stay unchanged, the 10-minute dedup window, the quote-is-upper-bound nuance for the billed range, and the caching/inheritance behavior. This is the kind of context annotations cannot carry, and it does not contradict the destructive/running-cost 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?

Four tight paragraphs that front-load purpose, then billing, then prerequisites, then inheritance/alternatives. Every sentence carries substantive information for a 23-parameter credit-spending tool, though it is dense enough that it could be trimmed slightly without loss.

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

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

Given the tool's cost and 23 parameters, the description covers billing, prerequisites, state eligibility, inheritance, alternatives, dedup behavior, and the follow-up call. An output schema exists, so return values need not be explained, and nothing an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: default billing of the reused range, that start_sec/end_sec defaulting makes the quote an upper bound, that only passed settings change and everything else is inherited, and the requirement that new_moments=false only works when the range matches the original.

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 ('Creates a new clip job from the same source video as an existing job') and immediately enumerates the differentiators (caption style, hook style, clip length, etc.). It cleanly distinguishes itself from create_clip_job (new job) and retry_clip_job (same settings) without needing the 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?

Explicit prerequisites ('run quote_clip_job... get the user's agreement and pass max_credits'), a clear state restriction ('Works for completed and failed clip jobs, not for jobs that are still running'), an explicit alternative for the same-settings case ('use retry_clip_job'), and a next step ('call get_clip_job with wait_sec=50'). When/when-not and alternatives are all named.

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 carry the generic safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds the semantics those annotations cannot: it is free, preserves job_id, refuses certain state combinations, and returns the job with status queued. This is genuine behavioral context beyond structured hints.

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

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

Front-loads purpose, then exclusions/alternatives, then failure triage, then the return status and the next call. Every sentence carries a distinct obligation; 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?

Given a 1-param, single-purpose retry tool with annotations and an output schema, the description covers the gaps that matter: what state is required, what is refused, what happens to a completed job, and what to do next. An agent has everything needed to invoke 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 coverage is 100% and the single job_id parameter is fully described in the schema (pattern, hex length, which tools produce it). The description adds no syntax or format detail, so the baseline 3 for schema-heavy tools is correct.

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+resource ('Re-runs a failed clip job with the same settings, free of charge, keeping the same job_id') and distinguishes itself from siblings recut_clip_job and get_clip_job by name. The agent can tell exactly what the tool does without opening the schema.

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

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

Explicit when-to-use ('when get_clip_job shows status failed'), when-not ('refuses jobs that are queued or processing... completed jobs'), and names the alternative (recut_clip_job) with the condition that selects it. Also recommends check_video_source for a repeating failure. Nothing is 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 declare readOnly/idempotent/non-destructive, so the safety bar is covered. The description adds genuinely useful non-obvious traits: media links expire after 15 minutes, shared downloads happen off-tool, and returned text is untrusted and wrapped in <untrusted_source_text>. It stops short of describing result size or failure modes, so not a 5.

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

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

Front-loaded with purpose and the catalog split, then pagination, then the expiry caveat. Dense but nearly every sentence carries operational value; the two catalog clauses are slightly verbose for the space they take.

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

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

With an output schema present, return values needn't be explained, and the description still covers modes, filtering, paging, link lifetime and untrusted content. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema for catalog (what each mode searches and returns) and ties cursor/limit into a coherent paging model. Query matching semantics (whole words, no stemming) are echoed from the schema rather than extended.

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 ("Searches B-roll videos and images") and immediately distinguishes the two catalog modes and what each returns. An agent can tell this apart from get_broll_asset, which is explicitly named as the refresh path.

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

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

Gives concrete when-to-use routing for catalog=mine vs shared, notes shared items are downloaded on the website, and names the alternative get_broll_asset with the condition (expired links) that selects it. Omit-query behavior is also stated.

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