Convert non-drop-frame HH:MM:SS:FF timecode to exact frame count and milliseconds at 24,25 or 30 FPS. One call costs 0.01 USDC on Base x402; customer-owned provider credentials use X-Provider-Key header where needed.
| Name | Required | Description | Default |
|---|---|---|---|
| fps | Yes | fps; see operation description for units and format | |
| timecode | Yes | timecode; see operation description for units and format |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely new behavioral context: a per-call cost of 0.01 USDC on Base x402 and the X-Provider-Key header for customer-owned credentials. It does not detail error behavior for invalid timecodes, but that is a minor gap.
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, front-loaded with the core purpose and followed by cost/auth details. Every clause carries information; 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 a simple two-parameter conversion tool with no output schema, the description covers purpose, input format, FPS constraints, pricing, and auth. It states the return values (frame count, milliseconds) but omits failure modes for malformed or drop-frame timecode, which would fully round it out.
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%, but the schema's parameter descriptions are placeholders deferring to the operation description. The description compensates by specifying the timecode format (HH:MM:SS:FF, non-drop-frame) and enumerating valid FPS values (24, 25, 30), which the schema does not capture.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource (convert non-drop-frame timecode), the exact input format (HH:MM:SS:FF), the two outputs (frame count and milliseconds), and the supported FPS values. An agent can distinguish this immediately from neighboring video tools like api_video_timeline or api_subtitle_offset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is strongly implied by the format and FPS constraints, and 'non-drop-frame' implicitly excludes drop-frame timecode. However, it never explicitly says when to use this versus alternative conversion tools, nor what to do with drop-frame input, leaving the agent to infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.