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

The annotations already declare openWorldHint=true, readOnlyHint=false and idempotentHint=false, so the write/external-model profile is known. The description adds one genuinely new behavioral fact — "Credits" — signalling that calls consume paid credits, but it leaves the two-step confirmed/confirmationToken flow and any job/asynchrony behavior unexplained.

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 and dense: the verb and the kind list come first, then the two discovery pointers, then the cost note. The telegraphic fragments ("Credits.", "catalog kind media_models") are compact but slightly cryptic and require the reader to infer the tuple syntax.

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 six parameters, a free-form nested `params` object, no output schema and openWorldHint=true, the description covers the kinds and credit cost but says nothing about what a successful call returns or whether it enqueues a job retrievable via get_job. It is adequate to select the tool but thin for executing it end to end.

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 100%, so baseline would be 3, but the description adds value where the schema cannot: it points at guide(generate_media) to enumerate the fields of the open-ended `params` object, which the schema leaves as additionalProperties with no structure. Kinds listed in prose duplicate the enum and add nothing, so it is 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 ("Make media for a page") and enumerates the six kinds it produces, which lets an agent match the enum to its intent without opening the schema. It does not explicitly distinguish itself from the sibling make_video, which is the nearest ambiguous alternative, so it stops short of a 5.

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 routes the agent to catalog(kind: media_models) for model/credit info and to guide(generate_media) for per-kind fields, which is real discovery guidance. However, it never states when to use this versus make_video or how the confirmation flow is sequenced, so usage is implied rather than specified.

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