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

Annotations already cover readOnly/idempotent/openWorld, yet the description adds substantial behavior the agent could not otherwise know: it returns an MCP image content block after a one-line summary, ChatGPT clients only surface the summary, Tailwind-hosted images are 1000px wide, and it fails with a URL-naming error for >4MB images, coverless videos, or refused fetches.

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 use case, then returns, then client caveat, then edge cases, then the account caveat — a sensible ordering. It is dense and long for a two-parameter read tool, but nearly every sentence carries distinct operational information.

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?

Even with an output schema present, the description covers the return shape, client-dependent visibility, sizing, and the full failure envelope, plus the multi-account prerequisite. Nothing an agent needs to call this correctly is 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 the baseline is 3, and the description goes further by stating where postId comes from and adding an accountId disambiguation policy (ask the user if multiple accounts) that the schema does not express.

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 ('see what one Pinterest Pin's picture looks like', 'returns the Pin's image as an MCP image content block') and explicitly scopes it to cover images, not videos or design variations. This separates it from get_post and get_pin_design which are the plausible alternatives.

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 explicit trigger conditions ('when you need to read the words in a graphic or match drafts to copy'), names the prerequisite ('a postId is already known') and its sources (list_posts, get_post, create_post). It also adds a when-not-to-decide rule: ask the user which account before calling if list_accounts returns multiple.

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