search_twitterapi_docs

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (search documentation), what it returns (ranked results with specific fields), and provides concrete examples of query behavior. It doesn't mention rate limits, authentication needs, or error handling, but covers core functionality well for a search tool.

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 well-structured with clear sections (purpose, usage guidelines, returns, examples). Every sentence adds value: the first establishes scope, the second provides usage context, the third describes outputs, and the examples illustrate practical application. No wasted words or redundancy.

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?

Given the tool's moderate complexity (search function with 2 parameters), 100% schema coverage, and the presence of an output schema, the description provides excellent context. It covers purpose, usage, returns, and examples, making it complete enough for an agent to understand when and how to use this tool effectively.

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?

With 100% schema description coverage, the baseline is 3. The description adds value by providing specific query examples ('advanced search', 'rate limit', etc.) and explaining when to use different max_results values ('comprehensive research' vs 'quick lookups'), which enhances understanding beyond the schema's technical specifications.

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 clearly states the specific action ('Search') and resource ('TwitterAPI.io documentation') with explicit scope ('API endpoints, guides, and blog posts'). It distinguishes from sibling tools like get_twitterapi_endpoint or list_twitterapi_endpoints by emphasizing comprehensive search across all documentation types rather than retrieving specific items.

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 'USE THIS WHEN' section explicitly states 'when you need to find information across the entire documentation,' providing clear context for when to use this tool. The examples further illustrate appropriate use cases, though alternatives among siblings aren't directly named, the comprehensive search purpose implicitly differentiates from more targeted sibling tools.

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