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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds meaningful behavioral detail by stating the operation 'persist[s] the image' and returns 'CDN-backed metadata', revealing a persistent side effect and the storage mechanism. It does not contradict the annotations and adds context beyond the schema.

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?

The description is a single sentence that front-loads the core action ('Render a share-card PNG') and then provides the key behavioral details (persist, CDN metadata). There is no filler or redundant material, and the title is not restated beyond the initial line, which is acceptable.

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?

The tool has a moderate complexity with 3 parameters, all schema-documented, and an output schema exists so return values need not be spelled out. The description covers the essential operation and side effects, though it does not state prerequisites like the review must already exist or the behavior when template_id is invalid. Given the output schema and sibling context, this is adequate.

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?

All three parameters have full descriptions in the schema (100% coverage), so the baseline is 3. The description's mention of 'optional template styling and aspect ratio' maps to template_id and ratio but adds no semantic detail beyond what the schema already provides. id is adequately described in the schema as the review identifier.

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 uses specific verbs and objects: 'Render a share-card PNG', 'persist the image', and 'return CDN-backed metadata'. This clearly distinguishes it from siblings like createReview (which creates review records) and deleteShareTemplate (which deletes templates). The tool name and id parameter description tie it to a specific review, making the purpose unambiguous.

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?

The description establishes clear context: it is used to generate a share-card image for a review, with optional template styling and aspect ratio. It does not explicitly name alternatives or exclusions, but no sibling tool performs a similar image-rendering function, so there is no competing choice to disambiguate. A 4 is appropriate because the context is clear but the description stops short of explicit when-to-use guidance.

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