clip_url

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

Annotations provide only destructiveHint=false, and the description carries the rest: the operation is asynchronous and returns a job, images are stored alongside the Markdown file, duplicate URLs return the existing clipping unless 'force' is used, folder-scoped credentials are rejected, files:upload is required, and idempotency is supported. This goes well beyond the annotation's minimal safety hint.

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 three tight sentences that front-load the action and result, then the async polling path, then constraints. Parentheticals carry real information (images downloaded, result_node_id) rather than padding.

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?

For an asynchronous job-creating tool with a three-parameter schema, the description covers the return path, the dedupe case, permission requirements, and credential limitations. Even though an output schema exists, the inline explanation of result_node_id and get_job polling is enough for an agent to call and follow up 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?

At 67% schema coverage, url and force are already documented in the schema, but the description adds the deduplication behavior that makes 'force' meaningful and notes idempotency support, which partially clarifies the undocumented idempotency_key parameter. It still doesn't explain the expected format or usage of idempotency_key directly.

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 gives a specific verb and resource: 'Save a web page's main article as a Markdown file ... into the user's clippings folder'. The stated output (.md plus downloaded images, background job) is distinct enough from siblings like fetch_url that an agent can choose without opening a 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?

Clear context for use (clipping an article page), plus explicit prerequisites ('Requires files:upload') and exclusions ('Not available to credentials limited to a folder'). It also routes follow-up work to siblings (get_job, read_text_file). It never names a competing tool such as fetch_url as the alternative for raw or non-article fetches, so 'when-not' guidance is implied rather than stated.

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