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

Beyond the readOnlyHint, openWorldHint, idempotentHint, and non-destructive annotations, the description discloses meaningful behavior: keyword matching covers both lot title and description, geographic results are distance-ordered, and each result includes source, title, house, location, current bid, close time, and a link. It also explains the full indexed source universe. No annotation contradiction exists.

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 dense yet efficient, front-loading the core purpose before explaining filters, behavior, return fields, and the sibling alternative. Every sentence earns its place, and the length is justified by the tool's 11-parameter surface.

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?

With no output schema and a high-parameter tool, the description still covers the source universe, all major filtering modes, full-text matching behavior, result ordering, return fields, and the sold-price alternative. An agent can invoke the tool and predict its response meaningfully without additional clarification.

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 the baseline is 3, but the description adds practical meaning beyond the schema: concrete keyword examples, the full-text-over-description nuance, the meaning of segment as commercial vs government, and a geographic search example. It does not deeply elaborate every parameter, but it helps an agent choose values effectively.

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 specific verb and resource: 'Search live US auction lots across every source Pipeworx indexes,' and then enumerates the source families and filter dimensions. It also explicitly distinguishes itself from us_auctions_sold_comps by directing sold-price queries to that sibling, so an agent can tell the tools apart.

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 clearly names us_auctions_sold_comps as the alternative when actual sold prices are needed, and it lays out distinct usage modes: keyword filtering, structured filters, and proximity search with near_zip + radius_miles. It does not contrast with every sibling such as us_auctions_closing_soon, but the primary use case and the key substitution are unambiguous.

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