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

Annotations already declare readOnlyHint=true, so 'Read-only' in the text is redundant, but the description adds real behavioral context beyond them: agency clients see only the PUBLISHED report, and the response includes error detail per AI step plus a cabinet link. It does not describe pagination or what happens when the id/title resolves to nothing, but for a read tool the disclosure is solid.

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?

It is a single front-loaded sentence that opens with the resource and access method before enumerating return contents, so the key routing information comes first. The parenthetical field list is dense but each item maps to a plausible user question, and the trigger phrases earn their place for intent matching.

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?

There is no output schema, so the description carries the return-value burden — and it does so thoroughly, giving the agent a preview of every section of the response. What remains missing is minor but real: behavior for a non-matching title and the exact meaning of the `top` limit.

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 coverage is 50%: 'research' is fully documented in the schema as id or partial title, and the description only echoes that. The undocumented 'top' parameter (1–15) is never explained — the description mentions 'the top customer pains' and 'the strongest client quotes' but does not state that `top` caps how many of each are returned, so an agent must infer it.

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 definition names a specific resource and scope — 'One market research (by id or title) in short' — and then enumerates exactly what the record contains (pains, quotes, ad guidance, status/version, AI steps, cabinet link). This clearly separates it from a listing tool, though it never names the sibling 'market_research_list' as the alternative.

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?

Usage is implied rather than stated: look up a single research by id or partial title, and the Ukrainian trigger phrases («що показало дослідження», «які головні болі клієнтів») hint at the question types it answers. There is no explicit when-to-use versus when to use the list tool, and no stated prerequisite for what to do if the title is ambiguous.

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