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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, but the description adds substantial context beyond them: destructive calls are previewed exactly as they will run with nothing sent, a confirm token is returned and must be resent, requests are signed server-side against the verified host, nonces are single-use and expire in 600s, and the tool never writes to the substrate.

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?

It is dense but front-loads the core purpose and the read/write split before the operational details. The provider-to-API-URL listing is long, though defensible for an open-world write tool where the agent must know where a request lands. No sentence is purely filler, but it is heavier than strictly necessary.

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 8-parameter, open-world, destructive write tool with no output schema, the description covers the full lifecycle: nonce acquisition, preview/confirm for mutations, per-provider routing, and the read refusal path. The only unaddressed area, return payload shape, is partly handled by noting each successful write returns the next nonce.

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, but the description adds real meaning: it explains the shared key layout with get_from_unl (provider · op · body · target), the shape of body for op 'http' ({method, path, query?, body?}), and maps each provider to the specific API host that receives the request.

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 — 'Change data in a tool the person has connected to Unl' — and enumerates concrete write scenarios (PostHog insights/dashboards, signed HTTP writes, non-read-only MCP tools, read-spec amendments). It explicitly distinguishes itself from the sibling get_from_unl, which handles reads, so an agent can route without opening either 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?

Gives explicit when-to-use (create/update/delete across connected tools) and when-not ('Reads are refused here and cost no nonce — use the get_from_unl tool with action=\'analytics\''). It also names the required nonce source and the destructive-request confirmation loop, so invocation conditions are fully specified.

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