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

Annotations already declare readOnly, idempotent, non-destructive, so safety needs no restating; the description instead adds what annotations cannot: that calls are free (cost profile), that it is a polling operation bound to a prior generate call, and the non-obvious concurrency behavior that takes of the same conversation render in parallel. It also names the failure/status surface (failed, error), which is the key behavioral signal for a polling tool.

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?

Compressed and front-loaded: purpose and returned fields come first, then workflow placement, then the argument shape. The trailing JSON argument dump is slightly awkward prose but earns its place given the 0% schema coverage, and the concurrency sentence is dense but load-bearing.

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 no output schema, the description correctly enumerates the return fields, plus cost, polling position, and parallelism behavior. It stops short of stating what an agent should do after a 'failed' status (retry vs. report_issue) or how the job id is obtained, which would fully close the loop for a job-polling tool.

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% and the single parameter is a nested object, so the description usefully spells out the exact call shape as {"path": {"id": ...}}, compensating for the bare schema. It does not explain where the id comes from (presumably returned by the generate call) or its format, leaving a small residual ambiguity.

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 a video job') and enumerates exactly what is returned: status with its value set (queued, running, completed, failed), progress, duration, error. It also positions itself in the workflow chain relative to kelpo_generate and kelpo_video_download, so an agent can distinguish it from sibling read tools like kelpo_get_shoot or kelpo_videos.

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 sequencing rule ('poll it after kelpo_generate, then kelpo_video_download') and a concrete when-not: never block waiting on it before launching the next take of the same conversation, because those render together. This is exactly the kind of alternative/exclusion guidance that prevents a common agent mistake.

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