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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it returns the full analytics payload, the shape matches get_research_run, and it only returns the newest completed run, which explains why a missing result is possible.

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?

Front-loads the one-line purpose, then the canonical use case, then the args list in a scannable structure. Slightly more verbose than strictly necessary in the middle paragraph, but every line carries actionable information.

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 read-only tool with no output schema, the description adequately closes the loop by describing the return payload and its relationship to get_research_run. The only omission is any mention of user_intent, and pagination semantics for the results array are only lightly implied.

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 only 20%, so the description must compensate, and it largely does: brand_id is marked required, report_type's two enum values and the omit-for-either behavior are explained, and results_limit/results_offset get ranges and defaults that add context beyond the raw schema. It does not mention the user_intent parameter, leaving one gap.

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?

States a specific verb and resource ('get the most recent ready prompt research run for a brand') and explicitly frames itself as the canonical 'what does my latest research show' tool. It also names the sibling combination (get_research_runs + get_research_run) it replaces, so an agent can differentiate it without opening schemas.

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?

Gives an explicit selection rule: prefer this over get_research_runs + get_research_run when you only want the current state. That is a concrete when-to-use statement naming the alternatives, with no inference required.

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