get_purchase_order

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

With no annotations provided, the description carries full responsibility. It discloses ERP-specific response envelopes (SAP/Netsuite/Dynamics), including data format differences (stringified decimals, /Date(ms)/ dates, JSON numbers, OData etag), and clearly states it 'Raises if the PO is unknown'. It does not mention auth or rate limits, but for a read-only getter this is strong disclosure.

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 well-structured with a one-line summary, a bullet for the parameter, then ERP-specific return details, and an error statement. Every sentence provides necessary information; there is no redundancy or filler.

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?

Despite having an output schema, the description adds substantial context about expected response shapes across three ERP systems, which is unlikely to be captured by generic JSON schema. It also covers error behavior and parameter semantics, making this fully self-contained for a getter tool.

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 only lists po_id with a type, providing zero semantic content. The description compensates fully by explaining it is the corpus PO id, giving a concrete example 'PO-8801', and labeling it as the join key across the entire kit – essential meaning absent from 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?

The description opens with 'Fetch one purchase order' – a specific verb and resource that clearly distinguishes this from sibling tools like list_open_pos (list) and get_invoice (invoice). The phrase 'as the configured ERP would return it' also sets accurate scope expectations.

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?

It states the tool fetches a single PO and calls po_id the 'Join key across the whole kit', implying this is the canonical lookup for cross-tool workflows. However, it does not explicitly exclude alternatives or name when to prefer this over related getters (e.g., get_approval_status), so it lacks explicit exclusions but provides clear context.

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