Get the Vehicle Behind a Contract

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

Annotations already signal read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond that: the standalone edge case with `{status: "standalone", vehicle: null, message: ...}`, the instruction to check `status` before accessing fields, and the fact that it returns the vehicle's own PIID rather than the order PIID.

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 structured with a one-sentence definition, a category tag, a clear bullet for the parameter, and a compact edge-case paragraph. Every sentence adds necessary information, and code formatting makes the special return case easy to parse.

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 a single required parameter, a clear edge case, sibling routing, and an output schema present, the description is complete. It explains the input source, the semantic distinction between order PIID and vehicle PIID, the standalone fallback, and what downstream tools to chain into—nothing needed for correct use is missing.

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 for piid is 0%, so the description carries full responsibility. The bullet explicitly defines piid as 'the ORDER's PIID (not the vehicle's own PIID)' and says where to obtain it, which is exactly the kind of disambiguation needed for correct invocation.

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: 'Get the contract vehicle (IDIQ, GWAC, FSS schedule, or BPA) this order was placed against.' It clearly distinguishes itself from siblings by noting the input is the ORDER's PIID and that get_vehicle/get_vehicle_holders are for downstream detail, so an agent can instantly tell this tool 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 gives explicit routing guidance: use get_vehicle for the vehicle's own ceiling/period detail and get_vehicle_holders to see competitors. It also tells the agent when NOT to read vehicle fields—when status is 'standalone'—and states the PIID source (search_contracts or get_contract), leaving little to inference.

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