Search opportunities

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

With no annotations, the description carries the disclosure burden; it usefully reveals default exclusion of expired opportunities and that a formatted list is returned. However, the claim that results are 'newest-first' by default is unqualified and conflicts with the schema's orderby default (relevance when a query is given), and the description never explicitly confirms the operation is read-only.

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?

Five sentences with no filler: purpose, filter model, default behavior, return/next-step, and slug-discovery tip are each front-loaded in a logical order. The category enumeration is a slight length cost but earns its place by clarifying catalog scope.

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 an 11-parameter, zero-required search tool with no output schema and no annotations, the description covers defaults, return semantics, and how to get full details, and the schema covers the rest. It is somewhat vague about the exact content of the 'formatted list,' and the sort-default ambiguity is a minor completeness gap.

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 the baseline is 3, but the description adds value by grouping parameters ('free-text query plus optional filters by opportunity type, country, funding, and free-form tags') and explaining how to obtain valid slugs. This helps an agent understand which parameters are meant to be combined and where to look up accepted values.

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 'Search the Opportunities Circle catalog' and enumerates the covered opportunity categories, making the verb, resource, and scope unambiguous. Calling it 'the main discovery tool' and pointing to oppcircle_get for full details differentiates search from sibling lookup/listing tools.

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?

It explicitly positions the tool as the main discovery entry point and gives concrete routing guidance: use oppcircle_get with the returned id for details and list_categories/list_tags for valid slugs. It does not explicitly state when to prefer oppcircle_latest or oppcircle_overview, so the guidance is strong but not fully exclusive.

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