Ragora

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

ReadOnly annotation confirms safety, while description adds substantial context: specifies return payload structure (names, descriptions, content types, stats, available operations, usage examples) and access scope ('you have access to'). Does not mention rate limits or pagination, but output schema handles return details.

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?

Three sentences structured logically: purpose, return values, usage guidance. No redundant text; 'Call this first' front-loads the critical workflow instruction. Efficient information density.

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?

Fully adequate for a zero-parameter discovery tool. ReadOnly annotation covers safety profile; output schema exists to document returns; description provides sufficient overview of what gets discovered and workflow positioning.

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?

Zero parameters present, which per guidelines warrants a baseline score of 4. No parameter description is required or possible given the empty input schema.

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 uses specific verb 'Discover' with resource 'knowledge bases' (synonymous with collections). It distinguishes from siblings 'search' and 'search_collection' by clarifying this returns metadata (names, descriptions, stats) rather than content search 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?

Explicitly states 'Call this first... before searching,' establishing the prerequisite workflow order and implicitly directing the agent to use sibling 'search' tools only after this discovery step. Clear temporal guidance on when to invoke.

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

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

Annotations declare readOnlyHint=true, covering the safety profile. The description adds valuable behavioral context about the federated scope ('across ALL'), but does not elaborate on search methodology (semantic vs keyword), ranking behavior, or performance characteristics. With output schema present, this is acceptable coverage.

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?

Three sentences that are perfectly structured: purpose declaration first, usage context second, and sibling alternative third. No redundancy or wasted words; every sentence earns its place.

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 presence of annotations (readOnlyHint), output schema, and only two simple parameters, the description successfully covers purpose, scope, and usage differentiation. It adequately prepares the agent to invoke the tool correctly without needing to describe return values (handled by output schema).

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% with 'Natural language search query' and 'Maximum number of results' clearly documented in the schema. The description does not add parameter syntax, formatting details, or examples beyond what the schema provides, warranting the baseline score of 3.

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'), resource ('knowledge bases'), and crucial scope ('ALL...at once'). It effectively distinguishes this from the sibling tool search_collection by emphasizing the broad, cross-collection nature versus targeted search.

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 ('when you want broad results or aren't sure which collection has the answer') and explicitly names the alternative tool for the opposite case ('For targeted search in a specific collection, use search_collection() instead').

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

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

Annotations declare readOnlyHint=true, establishing safety profile. Description adds no behavioral context beyond this (e.g., semantic vs keyword matching, ranking behavior, what constitutes a result). With annotations covering safety, this meets baseline but adds no supplementary behavioral insight.

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?

Two sentences, zero waste. First sentence states purpose; second provides essential prerequisite. Front-loaded and appropriately sized for the tool's complexity.

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?

Appropriate completeness given existence of output schema (not shown but indicated). Covers the critical workflow dependency (discover_collections). Missing only edge-case handling (e.g., behavior when collection_name not found) to be perfect.

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%, documenting all 5 parameters (query, collection_name, top_k, filters, custom_tags) comprehensively. Description mentions 'by name' which aligns with collection_name, but primarily relies on schema. Baseline 3 appropriate for high-coverage schemas.

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?

States specific verb (Search) and resource (knowledge base/collection) clearly. Implies specificity with 'by name' but does not explicitly distinguish from sibling tool 'search' (e.g., when to use specific collection search vs general search).

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?

Excellent explicit prerequisite: 'Use discover_collections() first to find available collection names.' Provides clear workflow guidance. Would be perfect if it also clarified when to use this versus the 'search' sibling (e.g., scoped vs global search).

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