search_collections

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

No annotations are provided, so the description carries the burden. It discloses important behavior (that a result with no platforms is an umbrella collection and not reservable) which is genuinely useful behavioral context beyond schema. However, it doesn't disclose return format, pagination behavior, or rate limits. Given zero annotations, the description partially compensates but leaves behavioral gaps.

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 compact (about 50 words) and front-loaded with the core purpose in the first sentence. The workflow guidance and differentiation are valuable additions with no wasted wording. Slightly verbose in the middle section with the parenthetical, but overall efficient.

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 is a search function with 3 parameters, moderate complexity, and an output schema present. The description covers the key workflow context, distinguishes from the sibling search tool, and warns about umbrella collections. It doesn't detail the output fields, but an output schema exists which reduces that burden. Fairly complete for a search tool.

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 0%, but the parameters are fairly self-descriptive from their names and defaults (term, limit, include_retired with defaults stated in the schema). The description does not add any parameter-specific semantics beyond the schema. Baseline 3 applies since the schema is the primary source and names are reasonably clear, but the description misses the opportunity to clarify terms like term matching behavior or effect of include_retired.

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 verb+resource ('Search reservable TechZone collections by name') and clearly distinguishes from the sibling tool search_catalog by naming it explicitly and contrasting the separate Backstage deployer catalog. It also describes the precise workflow (pick result, inspect, reserve), showing exactly what the tool returns and its role.

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?

Provides explicit when-to-use guidance (finding something to reserve), a step-by-step workflow (inspect with get_collection, check for platforms, then create_reservation), and explicitly distinguishes from the alternative search_catalog. This is exemplary usage guidance.

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