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

Beyond the annotations (destructive, open-world, idempotent, non-read-only), the description adds the credit-reservation semantic ('Reserves its credit ceiling once'), states the call is billed ('This is paid'), and marks the resulting work as recoverable and asynchronous. The one gap is that destructiveHint=true is never explained in terms of what becomes irreversible if the quote is mis-accepted, but the cost and idempotency context is genuinely useful.

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 short sentences with the paid-call and idempotency facts front-loaded and the review warning last; nothing is decorative. The opening clause is slightly dense but still parses cleanly.

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?

An output schema exists, so return values need no explanation, and the description covers cost, one-time credit reservation, recoverability, and the review gate. What is missing for a paid, destructive mutation is explicit idempotency keying (request_key) and the upstream quote step.

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 50%, with descriptions only on read_skills, publication_proposal_id, and expected_catalog_version. The description adds meaning for quote_id ('the exact observed quote') and max_credits ('within the creator's approved spending allowance') but says nothing about request_key or work_id, so half the parameters still rely on the schema alone.

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 concrete action chain: accept an observed quote, reserve a credit ceiling, and queue recoverable research or import. That is clearly more specific than the name alone, though it never states the verb 'start' directly and leaves the relationship to native.quote_social_research implicit rather than naming it.

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 supplies one explicit prohibition ('Do not start another request when the original needs review') and a caution that acceptance is not completion, which implies waiting rather than re-invoking. However, it never says to obtain the quote via native.quote_social_research first, nor points at native.wait_for_social_research or native.read_social_research for follow-up, so the workflow routing is only implied.

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