get_pinterest_boards

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

No annotations are provided, so the description carries full burden. It mentions the tool 'gets' data (implying read-only) and prompts for missing blog_id, but doesn't disclose behavioral traits like authentication needs, rate limits, pagination, error handling, or what the returned list includes (e.g., board names, IDs, metadata). For a read operation with zero annotation coverage, this is a significant gap in transparency.

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 appropriately sized with two sentences: one states the purpose, and another provides usage guidance for missing parameters. It's front-loaded with the main action. There's no wasted text, but it could be slightly more structured (e.g., bullet points for clarity), keeping it efficient but not perfect.

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 complexity (read operation with 1 required parameter), no annotations, no output schema, and 0% schema coverage, the description is incomplete. It lacks details on return values (what boards look like), error cases, authentication, or how to handle multiple brands. For a tool in a set with many siblings, more context is needed to ensure proper agent usage.

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 adds meaning by explaining 'blog_id' as 'Blog id of the Metricool brand account', which clarifies its purpose beyond the schema's generic 'Blog Id' title. However, with 1 parameter, this is minimal compensation; baseline would be 4 for 0 params, but here it only partially addresses the coverage gap without detailing format or constraints.

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 'Get' and the resource 'list of Pinterest boards', specifying it's for a 'specific Metricool brand (blog_id)'. This distinguishes it from sibling tools like 'get_pinterest_pins' which retrieves pins rather than boards. However, it doesn't explicitly contrast with other board-related tools (none exist in siblings), so it's not a perfect 5.

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 implies usage when needing Pinterest boards for a Metricool brand, and it mentions asking for blog_id if not provided, which gives some procedural guidance. However, it lacks explicit when-to-use vs. alternatives (e.g., compared to 'get_brands' or other platform-specific tools), and no exclusions or prerequisites are stated beyond the blog_id requirement.

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