pinterest_run_report

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

With no annotations, the description does the transparency work: it declares the operation is read-only, reveals that old/wide or async requests are auto-routed, and warns that column names are raw Pinterest names. These are non-obvious, useful behavioral facts. It stops short of covering pagination, error handling, permissions, or return format.

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?

Three short sentences with no filler. The most important fact, read-only Pinterest Ads report, is front-loaded, followed by the key routing behavior and the column-name caveat.

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 tool with 17 parameters, no output schema, and no annotations, this description is too thin to allow correct invocation. It does not explain date formats, filter/entityIds shapes, return payloads, or how raw column names map to results. It provides safe selection-level context but not execution-level completeness.

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 needs to compensate for 17 parameters. It only hints at two: raw column names for 'columns' and async/auto routing for 'executionMode'. It provides no meaning for required dates, level, filters, entityIds, or attribution parameters.

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 states a clear verb and resource: 'Run a read-only Pinterest Ads report.' It adds useful distinguishing details like auto-routing to async for old/wide requests and raw Pinterest column names. However, it does not explicitly differentiate itself from the many sibling report tools such as run_targeting_report or run_catalog_report.

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 explains some internal routing behavior ('old/wide or explicit async requests') but gives no guidance on when to choose this tool over sibling report tools. There are no exclusions, prerequisites, or explicit use-case instructions, leaving selection to inference.

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