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

Beyond the read-only annotations, the description discloses important behavior: curated and raw results are ranked together, curated results carry defaults and guardrails, raw paths must be resolved via get_endpoint_schema, and raw routes already covered by curated tools are suppressed. This materially helps an agent interpret results and avoid misusing raw endpoints.

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 front-loaded with the core purpose and then explains result handling efficiently. Every sentence adds operational value, with no redundant restatement of the tool name or schema.

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 that an output schema exists, the description need not enumerate return fields. It supplies enough context about result categories, routing decisions, and query semantics for an agent to invoke and use the tool correctly.

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%, so the description carries the burden for the single query parameter. It adds useful semantics by saying the query may be one or several keywords and gives examples like 'records', 'hrv metric', and 'plan a workout', though it does not specify exact keyword separator or matching rules.

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 and resource: find/rank curated tools and raw OpenAPI endpoints for keywords. It clearly distinguishes this discovery tool from sibling action tools by explaining that curated results name callable tools while raw results are API paths for nolio_api_read/nolio_api_write.

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 gives clear context for using the tool to find the best tool for a task and explains what to do with both result types: call curated tools directly, or use a raw path with the generic API tools and get_endpoint_schema. It names relevant alternatives but does not explicitly state when not to use this search tool.

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