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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds real context: it does not touch text or audio, a text with a video/youtube link is always left untouched, and the prior image is discarded only under 'replace'. It also discloses the shape of the result. Slightly overlaps with the enum description in the schema, but the mutation semantics are genuinely clarified.

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 the core action and the guardrail on when to use it, then moves to targets, semantics, and result. It is dense and mostly earns its length, though a few clauses (e.g., the target-type enumeration) could be trimmed without loss.

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 still tells the agent what the result reports, covers edge cases (existing images, video/youtube texts), target eligibility, and correct input sourcing. Nothing an agent needs to invoke it correctly appears to be missing.

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%, so baseline is 3, but the description goes further: it explains which element types are valid targets ('media_targets.image'), that 'text' must be copied verbatim from get_activity_content, and that you send the choice to illustrate a choice and the question to illustrate a question. This meaningfully disambiguates 'text' and 'in_item' beyond the schema text.

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 precise verb and resource ('Put one specific image, chosen by its id, on texts of the activity') and immediately scopes it against siblings like illustrate_items and search_image_library. An agent can distinguish it from the auto-finding tool without opening the schema.

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?

Explicit routing rules: use only when the image was user-pointed (from list_my_media or a chosen search_image_library candidate), use illustrate_items when the user just wants images found for them, and 'Call it ONLY when the user asked for images in their own words.' Names both the alternative and the selecting condition.

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