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

With no annotations, the description carries the full burden and does well: it discloses the matching mechanism (deterministic keyword matching, no LLM), the output's shape (ranked endpoints plus high/medium/low confidence), and that matching is scoped to the platform's own catalog. It omits operational traits an agent might care about, such as cost/rate limits (rate_call and buy_credits exist as siblings) or failure behavior on an unmatched task.

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?

Front-loaded with the core question and the POST/return contract in the first sentence, then the mechanism, then the sibling relationship. Dense but nearly every clause adds information; the nested parenthetical about model_advisor being recommendable is slightly convoluted and costs a reread.

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?

No output schema exists, so the description must convey return values, and it does at a high level (ranked endpoints, confidence label). For a 4-parameter, non-destructive lookup tool that is close to complete; the remaining gap is not naming the result fields or what an empty/low-confidence result looks like.

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%, so baseline is 3, but the description adds real meaning beyond the schema: it explains that `context` is meant for a prior model_advisor rationale or extra detail that doesn't fit in `task`, and that the tool pairs with model_advisor so the parameter has a concrete source. `tools` and `top_n` are left to the schema, which already documents them.

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?

Opens with a specific question the tool answers ('Which QL-API endpoint fits this task') and then states the action and return: POST a task description, get ranked endpoints with confidence labels. It explicitly differentiates itself from model_advisor and explains that model_advisor is itself in the recommendable catalog, so an agent can tell the two apart without reading either schema.

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?

Gives concrete invocation guidance — 'call them independently and chain the results yourself' — and names the optional `context` hand-off from model_advisor. It stops short of stating when this tool should NOT be used (e.g. when the caller already knows the endpoint, or in what order advice tools should be tried when both are relevant).

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