List boards

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely useful context the annotations do not: which account's boards are returned and the existence of ad-only PROTECTED boards. It says nothing about pagination or result limits despite a max_results parameter, so it adds only partial behavioral context.

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?

Two short blocks: a front-loaded statement of scope and intent, then a compact enumeration of privacy values. Nothing is padded, though the privacy list is presented without labeling it clearly as the accepted values for the privacy argument.

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 an existing output schema and full read-only annotations, the description covers what an agent still needs: whose boards are listed, the trigger parameter for that scope, and the valid privacy vocabulary missing from the schema. The only gap is pagination behavior for max_results, which is minor against the structured data already provided.

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 description coverage is 0%, so the description must compensate. It does explain ad_account_id's meaning and enumerates the valid privacy values (ALL, PUBLIC, PROTECTED, SECRET, PUBLIC_AND_SECRET), which the schema omits entirely as an enum. It leaves max_results undocumented, so one of three parameters carries no semantic guidance.

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 uses a specific verb and resource (list boards) and disambiguates scope: the caller's own boards versus the ad account owner's boards when ad_account_id is supplied. It also states the downstream motivation (to find Pins), which separates it from sibling read tools like list_pins and list_board_pins, though it never names those siblings explicitly.

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 a conditional usage cue for ad_account_id ('the ad account owner's with ad_account_id') and a purpose ('to find Pins'), so an agent can infer when to reach for it. However, there is no explicit when-not guidance or named alternative, such as using list_board_pins once a board is chosen, so routing is only implied.

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