Update instant url

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds value beyond that: it warns that provider scopes, locks and credits apply (external cost/side effects) and that only one submission is allowed, which is a real retry constraint. The jargon ('locks') is vague but the added context is genuine.

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 HTTP path, then three short clauses with no padding. 'Current Bannerbear V5 operation' is mild filler, but the whole definition stays tight and readable.

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 a destructive mutation with a nested payload object and no output schema, the description covers confirmation and cost/locks but never says which fields the payload updates or what happens to unspecified settings. Annotations carry the safety burden, so this is adequate but leaves gaps.

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 80%, so the schema already documents account, confirm, payload and payload_file. The description only implicitly touches the 'confirm' parameter via 'Mandatory confirmation' and adds no syntax or format detail beyond the schema, so 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?

The description names a specific verb+resource through the HTTP operation 'PATCH /v5/instant_urls/{uid}', making clear this modifies an existing instant URL. It doesn't differentiate from siblings like create_instant_url or delete_instant_url, but the verb and path are unambiguous about what is being acted upon.

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?

It provides a use prerequisite ('Mandatory confirmation before provider execution; one submission only') but never states when to choose this tool over create_instant_url or get_instant_url, nor what prerequisites the account/uid must satisfy. Usage is implied rather than explained.

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