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

With no annotations provided, the description carries the full burden and pays it off. It reveals row contents (clearing APR, bid count, own-account flag), the behavior when below MIN_COMPARABLES (rows still returned, no aggregate computed), and an explicit null-vs-false warning for the own-account flag. This goes far beyond the typical read-tool description.

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 efficiently structured: purpose, method, output contents, edge-case behavior, then a warning. Every sentence earns its place, and the important null-handling warning is clearly flagged. Despite covering substantial behavioral detail, it remains compact and scannable.

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 there is no output schema and no annotations, the description supplies the necessary response semantics: individual observations, row fields, threshold behavior, and the provenance caveat. It also names the distance dimensions and supports the seven optional parameters through the schema. An agent has enough context to invoke the tool and interpret results correctly without reconstructing hidden behavior.

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?

The input schema already covers 100% of parameters, establishing a baseline of 3. The description adds value by specifying how the parameters relate: matching is done by 'normalised distance on loan amount, LTV and tenor.' This information is not inferable from the individual parameter descriptions and clarifies which parameters drive the comparability computation.

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 a concrete question ('Which recent auctions resemble these parameters, and how did each clear?') and then gives a precise method: 'Nearest-k settled auctions by normalised distance on loan amount, LTV and tenor.' It clearly identifies the resource and behavior, and the emphasis on 'returns the individual observations' distinguishes it from aggregate-style or 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?

The intended use is strongly implied by the opening question and by describing this as a nearest-k comparables lookup, but the description never names a sibling alternative such as find_auctions_matching_criteria nor states when not to use this tool. There is no explicit exclusion or routing guidance.

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