Save a Pin to another board

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

Annotations only say readOnlyHint=false, destructiveHint=false. The description goes further by disclosing that the save endpoint COPIES rather than moves, leaving the original intact, and requires deleting via delete_pinterest_pin to remove the duplicate. Also states the 0-credit cost and Pinterest connection requirement, which are behavioral facts the agent needs to know.

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?

Approximately 150 words, but every sentence is functional: purpose, sibling comparison, copy behavior, user guidance, credits, and connectivity. The structure is front-loaded with the core purpose, then expands into usage and behavioral nuances. Slightly verbose but not wasteful.

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?

Given the tool's simplicity (3 params, no output schema), the description provides all necessary context: what it does, when to use it, how it behaves (copy vs move), what the agent must do (let user pick board), cost, and prerequisite. Nothing essential is missing for an agent to correctly invoke it.

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?

The description reinforces that boardId must come from list_pinterest_boards and that the user picks it, but this is already in the schema. It adds no new meaning for pinId or boardSectionId, and the optional boardSectionId is completely undocumented in both schema and description. With 67% schema coverage, the description adds marginal value beyond the schema.

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 ('save'), resource ('existing Pin'), destination ('another board'), and clearly distinguishes from update_pinterest_pin by calling itself the GENERALLY AVAILABLE option. The purpose is immediately obvious and differentiated from siblings.

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?

Explicitly says to reach for this first over update_pinterest_pin (which is in limited beta), and instructs the user to pick the board via list_pinterest_boards. Also provides cleanup guidance by pointing to delete_pinterest_pin if duplication is unwanted. No ambiguity remains about when to use this tool.

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