Delete a Pinterest board

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

Annotations already declare destructiveHint: true and readOnlyHint: false, but the description goes much further. It reveals the two-step confirmation flow, the behavior of the unconfirmed call (returns board details without deleting), the requirement to echo back confirmName and confirmChildren to prove intent, the irreversibility, the scope of deletion (pins, followers, collaborators), and the permission nuance making secret boards unavailable. It also notes the 0 credit cost and the Pinterest connection requirement. No contradictions with annotations.

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 long but every sentence carries essential operational or safety information. It front-loads the critical warning and then walks through the flow. While it could be formatted with bullets or sections for readability, the density is justified by the destructive nature and the complexity of the confirm process. It avoids redundancy and stays focused.

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 highly destructive tool with a non-trivial workflow, the description covers everything an agent needs: the precise call sequence, the information returned by the unconfirmed call, the significance of each parameter, the pitfall with the alternative, and the prerequisite (Pinterest connected). There is no output schema, but the description details the unconfirmed response. Comprehensive enough for safe and correct invocation.

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?

Although the schema already describes each parameter (100% coverage), the description enriches them significantly. It explains that confirmName and confirmChildren are echoes from the unconfirmed call and exist to ensure the caller has actually inspected the board. It clarifies why confirm is required ('the board and its Pins are gone for good') and how boardId is sourced from list_pinterest_boards. This goes well beyond the schema text.

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 states exactly what the tool does: 'PERMANENTLY delete a board AND EVERY PIN ON IT.' It uses a strong verb, specifies the resource, and emphasizes the irreversible scope. It distinguishes itself from sibling tools like delete_pinterest_pin and update_pinterest_board by highlighting the permanent deletion of the entire board and the unsuitability of the privacy alternative.

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?

The description gives explicit usage guidance: call without confirm first, show results, then call with confirm:true and the echoed values. It also explicitly warns against using update_pinterest_board(privacy:'SECRET') as an alternative, explaining why it fails (missing boards:write_secret permission), and states the reversible option lives in Pinterest's own app. This is exactly the kind of when-to-use/when-not-to-use guidance that helps an agent select and invoke correctly.

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