mcp

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

The description adds meaningful behavioral context beyond the annotations: it specifies that only queued or processing jobs can be cancelled, and that reserved credits are refunded. This complements the destructive and idempotent hints by clarifying the concrete effects.

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

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

The description is extremely concise: two short sentences that immediately state the action and a key consequence. Every word earns its place, and the main verb 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 simple single-parameter tool with an output schema and adequate annotations, the description is complete. It covers the purpose, the valid job states, and the refund behavior, which is all an agent needs to decide and invoke the tool correctly.

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

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

The parameter is fully described in the schema ('Job ID to cancel'), so the description doesn't need to add much. The description itself doesn't provide additional detail about the id parameter, but no gap exists because the schema covers it completely, meeting the baseline for high coverage.

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

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

The description clearly states the tool cancels a job, specifically one that is queued or processing, using a specific verb and resource. It distinguishes itself from siblings like create_job and get_job by the action and scope.

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

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

The description clearly indicates when to use the tool: when a job is queued or processing and needs to be cancelled. It doesn't explicitly mention alternatives or exclusions, but the context is clear enough given the sibling tool names.

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 discloses that the tool returns a job ID rather than a synchronous result, implying asynchronous processing, which is a behavioral trait beyond the readOnlyHint annotation. It does not mention error conditions or rate limits, but annotations already indicate a non-read-only mutation, and the addition of the get_job workflow adds meaningful context.

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 only two sentences, front-loaded with the primary purpose and immediately followed by actionable workflow guidance. No filler or redundant information is present.

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

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

The description covers the purpose, a prerequisite (list_tools), and the follow-up action (get_job), which is strong for a tool with rich schema annotations and an output schema. It does not mention cancellation or billing, but sibling tools and schema descriptions cover those aspects sufficiently.

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 100% schema description coverage, the baseline is 3. The description's reference to list_tools adds minor context for the 'tool' and 'options' parameters, but it does not significantly enrich parameter meaning beyond what the schema already provides.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Create a video/audio processing job.' It distinguishes itself from sibling tools by mentioning the job ID and the follow-up with get_job, unlike cancel_job or list_tools.

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

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

The description explicitly provides usage guidance: 'Use list_tools first to find the right tool and options' and 'use get_job to check status and get the result URL.' This names the prerequisite and subsequent tool, giving a clear workflow and effectively directing the agent away from using this tool for status checks.

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 annotations already declare readOnlyHint=true and idempotentHint=true, so safety profile is covered. The description adds no extra context about rate limits, response format, or other behavior. For a simple read-only balance check, this is acceptable but not additive beyond annotations.

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

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

The description is a single, concise sentence that conveys the complete purpose without any filler. It is front-loaded and every word earns its place.

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

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

Given the tool's simplicity (no parameters, read-only operation, output schema present), the description is fully adequate. It explains what the tool does, and the output schema covers return values. No additional context is needed.

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

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

The tool has zero parameters, so the baseline score is 4. There are no parameter semantics to explain, and the schema already reflects this with an empty properties object. The description does not add parameter-related detail, which is unnecessary here.

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

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

The description uses the specific verb 'Check' and clearly identifies the resource as 'current credit balance'. It is unambiguous and easily distinguished from sibling tools, which are all job-related (cancel_job, create_job, get_job, list_tools).

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

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

The description implies the usage: use this tool when you need to check your credit balance. However, it does not explicitly state when to use it versus alternatives, nor does it provide any exclusions or prerequisites. Given that siblings are unrelated, the implication is sufficient but not explicit.

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 and idempotentHint, covering the safety profile. The description adds a significant behavioral detail: the completed status yields a download URL valid for 1 hour, which is beyond the annotations and schema. This enriches the agent's understanding of the response behavior.

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

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

Two sentences, front-loaded with the primary action, and the second sentence adds a crucial expiration detail without waste. Every word serves a purpose, making the description highly 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?

With a single parameter, a detailed schema, an output schema present, and strong annotations, the description covers the essential behavior including the download URL expiration. It is sufficiently complete for an agent to invoke the tool and process the result 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?

The input schema fully describes the single parameter 'id' as 'Job ID returned by create_job', so schema coverage is 100%. The description adds no additional parameter semantics, matching the baseline score for high schema coverage.

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

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

The description uses the specific verb 'Check' with the resource 'status of a processing job', making the tool's purpose unmistakable. It clearly distinguishes from sibling tools like create_job and cancel_job by naming the exact operation.

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

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

The description states the direct use case: checking the status of a processing job. It implies this is the monitoring counterpart to create_job, but does not explicitly name alternatives or exclusions. Provides clear context without formal if-then guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe read operation. The description adds only that it lists 'all' tools and includes 'options', which is minimal additional behavioral context.

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

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

The description is a single sentence of 10 words, front-loaded with the verb 'List' and no redundant 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?

Given the tool's simplicity (zero parameters), annotations, and an output schema, the description covers the core purpose and includes the detail that options are returned. It is sufficiently complete.

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

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

The tool has zero parameters, so the description does not need to explain parameter semantics. Baseline of 4 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?

Description states 'List all available video/audio processing tools with their options', clearly identifying the verb (List), resource (tools), and scope (all available). This distinguishes it from sibling tools focused on jobs and balance.

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

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

The description implies this is for discovering available tools but does not explicitly state when to use it versus alternatives like get_job or create_job. No exclusions or alternatives are mentioned.

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