List Pins to promote

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

Annotations already declare a safe, idempotent read, so the description's remaining job is context, and it delivers: it explains that ad-only (protected) Pins are hidden unless the flag is set, and that ad_account_id is required for accounts you don't own. It doesn't touch result volume or pagination, which keeps it short of a 5.

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?

Four short sentences, purpose first, then parameter notes in decreasing order of importance. Nothing is repeated and no sentence is wasted; the telegraphic parameter lines still parse cleanly.

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?

With an output schema present, return values need no explanation, and the safety profile is covered by annotations. The description supplies the semantics missing from a 0%-coverage schema for nearly every parameter, with only the result-limit behavior left unaddressed.

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 coverage is 0%, so the description must carry all parameter meaning and it covers four of five: enumerated pin_filter values, an example value list for creative_types, the effect of include_protected_pins, and the ownership condition for ad_account_id. max_results is left entirely to its default of 50 with no pagination behavior described.

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 opening sentence names a specific verb and a scoped resource: Pins that are eligible to be promoted. That is meaningfully narrower than siblings like pinterest_ads_get_pin or pinterest_ads_list_board_pins, though the description never names those alternatives to sharpen the boundary.

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?

It gives conditional guidance for one parameter ('Pass ad_account_id ... needed when it isn't your own'), which is a real usage cue. But there is no statement of when to prefer this over list_board_pins or list_ads, and no exclusions or prerequisites beyond that single case.

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