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

The description explicitly states 'Classification: read-only' while the annotations declare readOnlyHint=false, and the same text describes mutation modes (validate_only, preview_only, execute) and write-oriented seat requirements. This directly contradicts the structured annotation and would mislead an agent about whether the call mutates state.

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 purpose is front-loaded, but roughly half the text is generic orchestration/UX boilerplate (use assistantSummary first, never display raw JSON, suggest the next best action) that belongs in a system prompt rather than a tool definition, and it duplicates the title verbatim with a double period. The tool-specific signal is buried in padding.

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 values need not be explained, and the description does cover mutation modes, partial-failure policy, and idempotency. But for a 16-parameter tool with 0% schema coverage and deeply nested approved-context objects, it omits any explanation of prerequisites, identity configuration requirements, or input structure, and its 'read-only' claim conflicts with the actual write behavior.

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 16 parameters, including large nested objects (advertiserContext with dozens of fields, marketContext, campaignContext), so the description carries the full burden — yet it only adds meaning for seatId/seatName and a node named idempotencyKey that is not even in the schema. The remaining parameters, including the entire advertiserContext payload, are left undocumented.

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 specific verb and resource — building a versioned advertiser research graph from configured identity and approved context — which is far more than a name restatement. It does not, however, differentiate itself from the many sibling research tools (get_world_research_profile, leanriq_build_world_research_profile, get_world_research_summary), so an agent gets the 'what' but not a decisive 'this one vs that one'.

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 provides real prerequisites for invoking the tool — the seatId/seatName requirement on the exact mutation call when more than one seat is authorized, and idempotencyKey derivation on omission — plus the available mutation modes. But it never says when to choose this tool over the adjacent get_world_research_* or build siblings, so the routing guidance is implied rather than stated.

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