list_dv360_insertion_orders

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

Annotations already declare read-only, idempotent and non-destructive behavior, so the description does not need to cover safety. It adds two pieces of real behavioral context the annotations cannot carry: a hard 200-item cap and the instruction to reuse the same native DV360 filter when fetching the next page. What it omits is whether the cap applies to the response or to page_size, and any auth/scope expectations.

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 clauses, front-loaded with the core action and result cap, with no filler. The trailing pagination note is slightly orphaned from its parameter but still earns its place.

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?

An output schema exists, so return-value explanation is not required, and the pagination hint covers the trickiest calling pattern. The gaps are the undocumented account/advertiser_id distinction and the interaction between the 200 cap and page_size, which matter for a five-parameter paged listing tool.

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% across five parameters, so the description must carry the full explanatory burden and it largely doesn't. It only clarifies the 'filter' parameter (a native DV360 filter, reused across pages) and gestures at paging, leaving account, page_size, page_token and advertiser_id undefined in both schema and prose.

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 gives a specific verb and resource ('List DV360 insertion orders settings') and explicitly rules out performance metrics, which is a meaningful distinction among the DV360 siblings. It does not differentiate itself from adjacent list tools such as list_dv360_campaigns or list_dv360_line_items, but the resource is unambiguous.

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 clause 'These are not performance metrics' is a genuine when-not-to-use signal and implicitly routes reporting needs to the report tools. However, there is no guidance on when to pick this over the other DV360 list tools, and no prerequisites are stated beyond the required advertiser_id.

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