Search Kilango Operations

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered by structured data. The description adds the useful context that it searches a specific API contract (openapi.json) and returns operationIds for use with a companion tool. With strong annotations in place, a 3 is appropriate since the description adds some context but doesn't disclose return format details like how many results, pagination, or how to interpret results beyond operationIds.

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 wasted words. The first sentence states the action and source; the second sentence states what it returns and how to use it. Every clause 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 this is a relatively simple search tool with only 2 parameters (both optional with defaults), strong annotations, and no output schema, the description is largely complete. It explains the purpose, source, and downstream flow. It could benefit from mentioning what the results look like (e.g., list of operationIds vs JSON), but the description already states 'returns operationIds', which is a sufficient return contract. A 4 reflects the minor gap around result formatting/pagination.

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 must compensate for the two parameters (query, limit). The description implies the 'query' parameter is the search term ('Search the full operator API contract...'), and 'limit' has a schema default. However, it doesn't explicitly describe what a query string should contain (e.g., free text vs operationId fragment), but the description's framing of 'search' makes the query semantics reasonably inferable. Given zero schema coverage, the description does partial compensation work, warranting a 4.

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 tool searches the full operator API contract (from /v1/openapi.json) for operations not covered by a curated tool, and returns operationIds usable with kilango_call_operation. The verb 'search' + specific resource (operator API contract) + scope ('operations not covered by a curated tool') is specific and distinguishes it from siblings like kilango_describe_operation.

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 explicitly states it searches for operations NOT covered by a curated tool, which tells the agent when to use it (when a desired operation has no dedicated sibling tool). It also explains the output is usable with kilango_call_operation, establishing the workflow relationship with its sibling. This is clear usage guidance with implicit exclusions for curated operations.

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