check_skill

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

Annotations give the safety profile (idempotent, non-destructive), and the description adds genuinely new behavior: no new charges, the polling cadence, and the recovery-only-on-retry_request rule. 'Read' phrasing sits slightly against readOnlyHint=false, but the recovery path legitimately mutates state, so this is tension rather than contradiction. Return contract (nextAction, completed links) is sketched but not fully specified.

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 what is read and the no-charge guarantee, then the polling/recovery rules in compact clauses. Dense with zero filler, though the middle clause stack reads as one long run-on that would be easier to scan as separate sentences.

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 async status-polling tool with no output schema, the description covers the essentials an agent needs: what states it returns, that no charges result, the polling cadence, and the exact branch conditions for recovery vs. aborting. Only parameter naming is left unaddressed.

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 description never mentions the two required parameters. The agent is not told that 'skill' is one of the five enumerated pipelines nor that 'requestId' is the UUID from the initiating upload call. The enum values are self-documenting only for 'skill'.

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: read skill images and their failure/refund states, keyed implicitly to a skill request. This clearly separates it from siblings like upload_skill_image and the generate_* tools. It stops short of naming a sibling or explicitly saying it is the polling companion to an upload.

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 prescribes the polling protocol: follow nextAction, wait afterSeconds (normally 10s), recover only on retry_request with exact parameters, and do NOT poll for payment/auth/input failures or daily limits. This is a full when-to-use / when-not-to-use contract.

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