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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes beyond that with a concrete safety protocol for batch writes: dry run, show the person the recap, wait for explicit 'yes' even if the request sounded explicit. That is real added behavior. It falls short of 5 because it says nothing about auth/scope requirements, error behavior, or whether a committed destructive call can be undone (relevant given undo_deletion/list_recent_deletions exist).

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 purpose and scope in the first two clauses, then parameter mechanics, then the safety protocol. Inline examples replace prose description, and the batch-commit rule is compressed into one dense but readable sentence. No filler.

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?

Output schema exists, so return values need no explanation, and the description stays focused on what the schema cannot convey: path formatting, body shape sourcing, and the confirmation workflow. For a generic destructive escape-hatch tool with 0% schema documentation, this is as complete as the description needs to be.

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 0%, so the description must carry all three parameters, and it largely does: `path` gets the critical format rule (no /api/v2 prefix) plus concrete examples across POST and DELETE, and `body` is explained as the JSON payload with a pointer to get_endpoint_schema for the exact shape. It never states that `method` must be one of the four listed verbs or gives its casing/format explicitly, which is the remaining gap.

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 action and resource ('Write to any Nolio API v2 endpoint') and enumerates the methods in scope (POST/PATCH/PUT/DELETE). The follow-up clause 'Use when no curated tool fits' separates it cleanly from the ~30 curated write siblings (create_planned_event, update_training_frame, delete_event, etc.).

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?

Explicit routing rule: use only when no curated tool fits, which is exactly the discriminator an agent needs against the large sibling set. It also names a required prerequisite step ('check the exact shape with get_endpoint_schema first') and prescribes the multi-call commit flow, so the agent knows both when to select this tool and what sequence to run.

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