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

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds valuable behavioral context: 'Read-only, 0 credits' and 'Needs Pinterest connected (Settings ▸ Connectors ▸ Pinterest).' The credit cost and connectivity requirement are not present in the annotations, adding new information. The 'Read-only' phrase is redundant with the annotation, but the rest provides additional transparency without contradicting the structured data.

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 concise, consisting of two sentences with no wasted words. The primary purpose is stated first, followed by critical usage guidance. The directive 'ALWAYS call this before post_to_pinterest' is front-loaded, ensuring the agent sees the most important context early. This is an efficient, well-structured description.

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 read-only listing tool, the description covers all essential context: it explains what is returned (id, name, privacy, pin count), the prerequisite (connected Pinterest account), and the critical usage rule (call before post_to_pinterest and let user pick). No output schema exists, so the description carries the burden of describing the return values, which it does. The tool is simple, and this description is sufficient for 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?

The single parameter 'privacy' is fully documented in the schema with an enum and description ('filter by board privacy; default is everything the connection can see'). The tool description does not add any additional meaning about the parameter beyond what the schema already provides. Since schema description coverage is 100%, the baseline score of 3 is appropriate; the description correctly relies on the schema for parameter semantics.

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 clearly states the verb (List), the resource (boards on the user's connected Pinterest account), and the specific fields returned (id, name, privacy, pin count). It distinguishes itself from sibling tools like list_pinterest_pins and create_pinterest_board by focusing purely on listing boards. The additional directive to call before post_to_pinterest further helps differentiate its intended role.

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 explicitly instructs when to use this tool: 'ALWAYS call this before post_to_pinterest' and explains the reason—'Pinterest requires a board and Hermoso never chooses one for them.' This gives clear context and explicitly states the user must pick a board, preventing misuse. It also notes the prerequisite of Pinterest being connected, adding actionable steps.

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