awesome_list_search

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: archived repositories are excluded, results are external data to treat as data not instructions, data is fresh for 6 hours, and topic matching has quirks (exact-match base word, retry with shorter words). This goes well beyond the structured 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?

At roughly 180 words, the description is longer than the ideal two-sentence tool blurb, but the length is justified for an 8-parameter tool with nuanced matching behavior. It is front-loaded with purpose and usage, then structured into caveats and safety guidance. Minor redundancy exists ('beyond what free-text web search can offer' reappears later), but overall it is well-organized.

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 complexity (8 parameters, output schema exists, annotations present), the description is complete. It covers return contents, freshness, archived exclusion, external-data safety, topic-matching failure handling, and alternatives. With a full output schema available, further return-value detail would be redundant.

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 100%, so a baseline of 3 applies. The description adds meaningful parameter semantics beyond the schema by explaining the topic/query relationship, providing concrete examples ('osint', 'go'), and detailing exact-match behavior on base words with retry guidance. It does not fully enumerate every parameter, but the schema already handles that.

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 opens with a specific verb and resource: 'Search the ecosyste.ms Awesome API for community-curated "awesome-*" lists on a GitHub topic'. It clearly defines the scope (structured, complete coverage of the awesome-list ecosystem) and distinguishes itself from web_search by emphasizing ranked, filterable, structured results.

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 explicitly states when to use this tool versus alternatives: 'Use web_search with the awesome-lists lens for broader free-text discovery; use this tool when you want ranked, filterable, structured coverage of a specific topic's curated lists.' It also provides a practical retry strategy for zero-result misses, guiding the agent through common failure cases.

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