Get part details

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

Beyond readOnly/idempotent annotations, it discloses null semantics for missing catalogue facts, that stock and asking prices neither reserve supply nor guarantee fitment, and the exact failure shape (isError=true with structuredContent.error). These are non-obvious behavioral traits an agent could not infer from 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?

Front-loaded with the action and the ID constraint, then the return surface, then error semantics, then sibling routing. The enumerated return list is long but earns its place because no output schema exists; a couple of clauses could be tightened without loss.

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?

For a single-parameter read tool with no output schema, the description covers inputs, return fields, null handling, error behavior, and trust caveats about stock and fitment. Nothing an agent needs to call it correctly 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 is 100% and already says the ID is not an OEM number or URL, so most parameter meaning is structured. The description reinforces the constraint and adds the workflow origin ('from search_parts'), which is modest but real value on top of the schema.

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?

States a specific verb and resource ('Retrieve full public detail for one selected spare part') and implicitly contrasts with search_parts by requiring an already-known ID. An agent can tell this apart from search_parts, get_vehicle, and the handoff/guide tools without opening a 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?

Explicitly names the source of the ID ('Use part_id from search_parts'), states exclusions ('do not substitute an OEM number, chassis code or product URL'), and gives a fallback ('Search first when the ID is unknown'). It also routes to prepare_buyer_handoff and get_buying_guide for the adjacent intents.

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