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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds the important behavioral context of duration (~10 minutes), asynchronous polling, credit consumption after the first free run, and account requirement. This gives an agent a clear sense of side effects and cost without contradicting annotations.

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 description is long but front-loaded with the action before diving into output, timing, cost, and alternative-routing. Every sentence carries distinct operational information, and the density is justified by the tool's asynchronous, credit-consuming nature. It is not bloated, though not as terse as the ideal.

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 complex side-effecting tool with no output schema and no required parameters, the description supplies the necessary context: what it processes (posts/comments and angles), what it returns (ranked communities and plans), how to retrieve results (research_get), and cost/prerequisites. The only minor ambiguity is which tool to call for the signup link, but this does not block correct invocation.

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?

The input schema covers 100% of the five optional parameters with descriptive text for focus, productId, extraCompetitors, excludeSubreddits, and includeSubreddits. The description contributes context about what the run does with subreddits but does not add per-parameter semantics beyond the schema, so baseline 3 is appropriate.

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 opening clause names a concrete action and resource ('Start a hosted Community research run for a product') and the rest enumerates the exact research scope and output. It also distinguishes itself from research_get ('poll research_get') and social_* reads, so an agent need not confuse it with sibling tools.

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 gives explicit when-and-how: it is asynchronous ('Takes ~10 minutes; poll research_get'), metered after the first run ('later runs use AI credits (see get_usage)'), and explicitly says not to reproduce it with social_* reads. It also states the prerequisite of a free Prowlo account and where to get a signup link.

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