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

Annotations only flag the operation as non-read-only, idempotent and open-world; the description adds substantive behavior beyond them: extraction is asynchronous, its result becomes available to script generation, and duplicate attachment is deduplicated. It does not say how to observe completion or what happens on quota overflow.

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?

Four tight sentences that front-load what is attached and that extraction starts in the background, then add constraints. No filler or restatement of the title.

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 and light annotation coverage, the description covers the mutation's safety-relevant behavior well (async, idempotent, quotas, PDF precondition). Minor gaps remain around the identifier parameters and how the caller learns extraction finished.

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 only 33%, and the description documents the source shape (text length, PDF path origin) which the schema already partially covers, but leaves contentId and brandId completely unexplained — no hint on which content card is being modified or how brandId relates to it. It does add the 200–150000 character bound and the create_content_source_upload provenance for pdfPath.

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 ('Attach an article URL, raw text ... or uploaded PDF') plus the consequential side effect ('start AI extraction in the background'). An agent can distinguish this from create_content_source_upload (which only stages a PDF) and get_content_source (which only reads).

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 concrete operating conditions: PDF URLs must be downloaded by the agent and uploaded first, reattaching returns the existing ID, and quotas (max 5 sources / 3 PDFs per card). It never names a sibling as the alternative tool, so the routing is implied rather than explicit.

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