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

Annotations provide no safety hints (all false), so the description carries the full burden. It discloses key behaviors: the link expires (referencing expiresAt), the page automatically resizes and attaches the image, and the flow requires user interaction. This is useful behavioral context beyond the bare operation, though it does not mention permissions or failure modes.

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 dense but every sentence earns its place: purpose, usage condition, required params, workflow, expiration, and follow-up verification. It is front-loaded with the core decision ('the right tool whenever...') and avoids filler or redundancy.

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?

Given the tool's interactive flow and the presence of an output schema, the description covers all necessary context: when to use it, how to invoke it, what to do with the result, what not to do afterward, and how to confirm success. No critical operational detail is missing for an agent to call it correctly.

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 the baseline is 3. The description adds minor value beyond the schema—clarifying the interactive workflow and giving placement examples (header_photo)—but it does not substantially enrich parameter meanings beyond what the schema already states (e.g., editToken required for demo pages, placement enum meanings).

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 states a specific verb and resource: 'Get an upload link for a photo on the user's own device'. It explicitly distinguishes itself from siblings: 'the right tool whenever the image is not already at a public URL', and warns 'do NOT call media_attach afterward'. This makes the tool's purpose and boundary 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 gives explicit when-to-use guidance (image not at a public URL), required parameters (pageId, editToken for demo pages, placement), and follow-up steps (show link to user, call page_get to confirm). It also provides an exclusion ('so you do NOT call media_attach afterward'), leaving no ambiguity about the correct workflow.

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