ecosystem_search_by_capability

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

No annotations are provided, so the description carries the behavioral disclosure burden. It's a read/search operation (implied by 'search'), but nothing explicitly states that it's non-destructive, whether results are paginated defaults, or how the tags parameter behaves (AND vs OR semantics are only in the schema). The description adds the reverse-lookup framing over the schema but doesn't disclose behaviors like default sort, pagination bounds, or that match_mode controls tag combination. Schema covers some of this.

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 a single crisp sentence that front-loads the verb and resource, then adds the distinguishing parenthetical. Zero wasted words — every token earns its place. This is model conciseness.

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?

The tool has an output schema (so return format is documented elsewhere), 100% schema coverage for all 7 params, and a clean single-sentence purpose statement. For a read/search operation with well-documented schema and output, the description is reasonably complete. It could marginally improve by noting it complements ecosystem_search and is non-mutating, but the output schema + full param docs offset most gaps. Given the tool is a simple filtered search, this is near-complete.

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 description coverage is 100%, so all 7 parameters are already documented in the input schema. The description adds minimal parameter-level value beyond the schema — the reverse-lookup framing helps understand tags, but the description doesn't explain parameter interactions like how match_mode 'all'/'any' combines multiple tags or how min_stars/max_stars bracket popularity. The schema carries the burden, 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 description 'Search ecosystem repos by capability tags (reverse lookup from tag → repo)' clearly states the verb (search), resource (ecosystem repos), and the distinguishing characteristic (reverse lookup from tag to repo — the inverse of a forward tag search). This differentiates it from sibling tools like ecosystem_repo_tags, and the parenthetical adds useful clarity. It loses a point because the exact semantics of 'capability' vs general tags is not fully explained.

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 notes this is a reverse lookup from tag→repo, which implies it's the inverse of ecosystem_repo_tags (repo→tags). However, there is no explicit when-to-use/when-not-to-use guidance, no stated alternative tools, and no comparison against ecosystem_search (the likely forward search sibling). The parenthetical hints at positioning but doesn't explicitly guide tool selection.

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