Get Price Position

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

The annotations already establish read-only and idempotent behavior, and the description adds meaningful context beyond them: Pro-only access, a maximum sample limit of 25, output chaining via recipient_uei and award_id_piid into profile/contract tools, and the caveat that it is not a bid recommendation. There is no contradiction with the annotations.

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 outcome, then adds usage context, a parameter bullet list, chaining guidance, and a caveat. Each sentence and bullet adds distinct value, with no filler, and the structure makes the 10-parameter surface manageable.

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 10 parameters with zero schema descriptions, this description is unusually complete: it covers the required fields, the key constraints, the interpretation of results, and downstream tool chaining. The cross-reference to get_price_benchmark for shared filters is acceptable because the sibling is present in the same tool set, and an output schema exists for return-value details.

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?

With 0% schema description coverage, the description carries the parameter-documentation burden. It clearly defines naics format, value format with examples, and sample_limit semantics and cap. The optional filters are grouped as 'same as get_price_benchmark', which is efficient but not fully self-contained for an agent that may not have that sibling's docstring at hand.

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 opening sentence states a precise operation: compute the percentile rank of a supplied contract/bid value against comparable contracts and return nearest samples. It also explicitly contrasts the tool with get_price_benchmark, making the identity and position in the tool family unmistakable.

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 names the direct alternative (get_price_benchmark) and explains the distinguishing condition: one places a specific number in the range, the other just returns the market range. It further scopes usage to Bid & Proposal / Negotiate, notes the Pro-only restriction, and clarifies the output is factual positioning, not a recommendation.

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