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

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description aligns with that (no destructive claims). The description adds key behavioral details beyond annotations: caching for 7 days, the need for force:true to refresh, and the deferred side effect where expanded keywords are applied to the next generate_posts run. It also clarifies that other outputs are dormant until enabled. This is transparent about what the tool does and its downstream effects.

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 dense but well-structured. It front-loads the critical 'FREE pre-flight' label, then lists the outputs, then distinguishes automated vs. dormant results, and finally covers caching and force. While a bit long, every sentence contributes to correct invocation and expectation-setting. The structure effectively prioritizes the most important 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 research tool with no output schema, the description provides a thorough inventory of what the agent will receive (expanded keywords, phrases, influencer accounts, lists, competitors) and how to act on each category. It covers the caching mechanism, the free nature, and the interaction with other tools (generate_posts, update_campaign). This is sufficient for an agent to understand when to call the tool and what to do with the results, though it could mention prerequisites like campaign existence or error conditions.

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 schema covers force with a description but leaves campaign_id undocumented (50% coverage). The tool description compensates by explicitly mentioning 'pass force:true to refresh' for force, and it implicitly defines campaign_id as the campaign being researched ('analyzes the campaign's keywords/topic'). While campaign_id is not explicitly described, its purpose is self-evident from the context, so the description adds meaningful semantic value beyond the schema.

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 action ('analyzes the campaign's keywords/topic') and lists concrete outputs (expanded keywords, high-intent phrases, influencer accounts, relevant X lists, competitors). It explicitly distinguishes itself as a 'FREE pre-flight' research step, differentiating it from get_research (which likely retrieves stored results) and generate_posts (which applies the results). The verb and resource are 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?

Strong usage guidance: it tells the agent to use this tool 'before spending credits' and explains exactly which outputs are applied automatically (expanded keywords and exclusion terms via the next generate_posts run) versus which require enabling sources via update_campaign (free). It also addresses the caching scenario and how to force a refresh. This gives clear when-to-use and when-not-to-use context.

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