Create an ad-only Pin

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

Goes well beyond the annotations by disclosing the side effects of creation: the Pin lands on a protected 'Ad-only Pins' board and cannot be saved by others or shown organically. It also names the required auth scope with the exact command to grant it, and warns that trial-access apps produce Pins only the creator can see — auth, visibility, and side-effect context the readOnly/openWorld hints do not carry.

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-loads the verb and resource, then layers on constraints and auth in compact sentences with no filler. Slightly dense and mixes operational instructions (the auth command) with conceptual explanation, but every sentence earns its place.

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 the hard parts of a creation tool: auth scope, visibility semantics, and AI-disclosure obligations. The gap is the under-documented optional params, particularly board_id, which sits awkwardly against the stated fact that ad-only Pins live on a protected system board.

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?

With 0% schema description coverage across 8 params, the description must carry all meaning, and it only covers a subset: ad_account_id (ownership), ai_disclosures (with the valid values AI_MODIFIED and SYNTHETIC_PERFORMER), and image_url implicitly. The remaining params — link, title, alt_text, description, and especially board_id — get no explanation of their role or relationship to the protected ad-only board.

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 ("Create an ad-only Pin from an image URL") and immediately gives its downstream role ("to use as an ad's pin_id"), which separates it from pinterest_ads_create_ads and the general Pin/board readers in the sibling list. The follow-up sentence defines what an 'ad-only Pin' actually is, so the agent isn't guessing at the concept.

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?

Explains the context in which this tool is appropriate (ad creative supply, not organic posting) and gives an operational instruction to pass ad_account_id so the Pin belongs to the right profile. It stops short of explicitly routing the agent to pinterest_ads_create_ads as the next step, so the workflow is implied rather than stated.

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