stivio-mcp

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds information annotations cannot express: the call is free and reserves no credits. It still doesn't say whether validation failures surface as errors or as a field in the response.

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

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

Two tight sentences with the cost outcome front-loaded and the no-side-effect guarantee immediately after. Zero waste.

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

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

For a 4-param, no-output-schema tool, the description conveys the primary return (credit cost) but leaves the shape of validation results unstated and says nothing about accepted resolution/duration ranges. Adequate but with clear gaps an agent would hit on first call.

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

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

Schema description coverage is only 25% — duration, resolution (no enum), and audio have no descriptions anywhere. The description mentions no parameters at all, so it does not compensate for the coverage gap; it only hints that settings will be validated.

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

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

States specific verbs and outcome: 'Validate settings and calculate the exact credit cost.' The clause 'does not generate or reserve credits' functionally separates it from generate_video without naming the sibling explicitly.

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

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

Implies the pre-generation estimation use case via 'Free; does not generate or reserve credits,' but never says 'call this before generate_video' or names any alternative. An agent must infer the workflow placement.

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

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

Goes well beyond the annotations: discloses that the job is paid and requires user approval, that requestId deduplicates identical retries for 24h, the explicit rule against minting a new id after an uncertain outcome, and that it returns taskId. This is exactly the destructive/monetary context an agent needs before firing a write.

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 dense sentences, front-loaded with the monetary/approval fact, then the retry rule, then the return value, then the i2v/t2v routing. Nothing is repeated from the schema or annotations.

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

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

For an 11-parameter paid mutation with no output schema, the description nails the safety and retry story but leaves the majority of parameters and the valid duration/resolution domain unexplained. It's adequate to call safely but not complete enough to call optimally.

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

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

Schema coverage is only 18%, so the description must carry the load, and it only clarifies requestId dedup semantics, expectedCredits, and the model naming convention. undefined behavior for duration, resolution, aspectRatio, audio, multiShots, lastFrameUrl, and prompt remains with no explanation in either place.

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

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

Specific verb+resource ('Start a paid video job') with the key distinguishing attributes (paid, approval-gated, expectedCredits quote) stated up front. An agent can separate this from estimate_video_cost, get_video_status, and upload_image without opening any schema.

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

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

Explicitly routes the i2v path through upload_image first and the t2v path through a '-t2v' model, which is real when-to-use guidance tied to siblings. It doesn't state preconditions like needing a quote from estimate_video_cost or sufficient balance, so it stops short of full routing coverage.

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, closed-world behavior, so the bar is lower. The description still adds value with the auth requirement ('requires a key') and the explicit boundary that it does not reconcile balances, which the 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?

Two short sentences with the core action front-loaded and no filler. The trailing 'does not render videos' clause is slightly tangential but does serve as scope disambiguation.

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

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

For a zero-parameter, read-only tool whose safety profile is fully covered by annotations and with no output schema to explain, the description is nearly complete. Only minor gaps remain, such as the balance's unit or format.

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

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

There are zero parameters and 100% schema coverage, so parameter semantics are trivially complete; the baseline of 4 applies since no parameter meaning needs explaining.

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 your spendable Stivio credit balance') with the scope qualifier 'spendable', which distinguishes it from cost-estimation siblings like estimate_video_cost.

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 exclusions ('does not reconcile or render videos') and a prerequisite ('requires a key'), but never names the actual alternative for related needs, such as estimate_video_cost or list_video_models. Usage is implied rather than explicitly routed.

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 substantial context beyond the annotations: a rate limit, the success payload (videoUrl), failure/refund behavior, storage/refund finalization side effects, and a key requirement. These disclosures are consistent with the non-read-only, open-world annotations.

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

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

The description is compact and front-loads the purpose and polling constraint. The final sentence about finalization and key requirements is slightly fragmented but still efficient.

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 polling tool with annotations and no output schema, the description covers rate limiting, success output, failure/refund behavior, side effects, and auth requirements. It still leaves the taskId origin and exact failure response shape implicit.

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

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

The only schema parameter, taskId, is never explained; with 0% schema description coverage, the description should clarify where it comes from or its format. The mention of 'requires a key' introduces an auth concept that is not represented in the schema and may muddy parameter interpretation.

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 identifies a status-check on 'your own task' and states the success return (videoUrl for the MP4), so the purpose is clear. It does not explicitly name video generation or differentiate itself from siblings such as generate_video.

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

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

It provides a concrete polling constraint ('no faster than every 10 seconds'), which is useful procedural guidance. However, it does not explicitly say when to call this relative to generate_video or name any alternatives/exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuinely new behavioral context not in the annotations: it is public and requires no API key, which affects how an agent calls it. It stops short of describing result shape or whether 'settings' is exhaustive.

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

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

Two short sentences, zero filler, with the resource and payload front-loaded and the access note trailing. Nothing redundant.

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

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

A simple read-only listing tool with one optional param and no output schema; the description adequately covers what the tool delivers and how it is accessed. The only material gap is the unexplained 'mode' filter, which for a low-complexity tool keeps it short of full completeness.

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

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

Schema description coverage is 0% for the single optional 'mode' parameter. The description says nothing about it, and the enum values 'i2v'/'t2v' are unexplained abbreviations (image-to-video vs text-to-video) whose filtering effect and default-when-omitted behavior are left entirely unaddressed.

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

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

States a specific verb and resource ('List Stivio video models') plus the payload contents (supported settings, per-second credit rates). It clearly reads as a discovery/catalog tool distinct from generate_video or estimate_video_cost, though it never names a sibling to contrast itself with.

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

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

'Public; no key needed' gives context on accessibility, and listing models implies a discovery-before-generation use case, but the description never says when to call this versus estimate_video_cost or generate_video. Usage must be inferred.

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 real behavior beyond the annotations: the upload is moderated, there is a 3 MiB decoded cap, raw base64 is mandatory (no data URL), and a Bearer key is required for auth. What it omits is failure behavior — what a moderation rejection or oversize error looks like — and any rate limits, which keeps it off a 5.

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

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

Four sentences, front-loaded with purpose, followed by format/size constraint, output usage, and the alternative transport path. Every sentence carries information, though 'Requires a key' and the repeated 'Bearer key' could be merged into one auth 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?

A two-parameter tool with no output schema, and the description covers the essentials an agent needs: input encoding rules, size ceiling, auth, and that a url comes back and where to put it. Error/moderation-outcome handling is the only meaningful 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?

With 0% schema description coverage, the description must carry parameter meaning, and it largely does: it explains that base64 must be raw without a data URL prefix and bounded to 3 MiB decoded, and it enumerates PNG/JPEG/WebP matching the mimeType enum. It never states parameter names or pre-decode size expectations, so a 4 rather than a 5.

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

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

States a specific verb and resource ('Upload and moderate a ... image') plus the downstream purpose ('for video generation') and accepted formats. This is clearly distinguishable from every sibling (cost estimation, generation, status, model listing), none of which handle image ingestion.

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 usage conditions and an explicit alternative path: clients with file/shell access should POST multipart to the given endpoint instead of transcribing bytes through the model. It also routes the agent downstream by telling it to feed the returned url into imageUrl or lastFrameUrl.

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