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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the real burden and does: it discloses that the call does not upload the bytes itself but returns a presigned S3 URL plus a curl command to run locally, then hands back an s3_key. It also states the 100 MB ceiling, the supported MIME families, and the PDF-to-LinkedIn-document behavior — none of which is inferable from annotations or 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?

Front-loads the routing decision, then the reason, then the mechanics, then limits and the PDF edge case. Every sentence carries operational information; nothing is repeated from the name or annotations.

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 correctly explains the return shape (presigned URL + curl command + s3_key) and the downstream consumption pattern, plus size and format limits. Minor gaps remain: presigned URL expiry/retry behavior and whether the uploaded asset is scoped to an account or workspace before draft_post uses it.

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% for the two parameters (filename, content_type), so the schema already explains them including extension-based inference. The description's format list ('JPEG, PNG, GIF, WebP…') loosely constrains content_type but adds no syntax, defaults, or naming conventions beyond the schema. Baseline 3 applies.

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 ('attaching images, videos or a PDF to a post') and explicitly positions itself as the PRIMARY path versus the two named alternatives (inline base64, file_path). An agent can distinguish it from generate_image or attach_reference without opening any 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?

Gives an explicit selection rule ('Call this FIRST for any image beyond a thumbnail'), explains why the alternatives fail (parameter size limit, remote MCP server), and names the downstream tools and field (draft_post / save_draft / update_draft via `images`). It also carves out the PDF case with its own constraint (LinkedIn only, on its own post).

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