procurement_po_history

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

The description adds substantial behavioral context beyond the readOnlyHint annotation: it explicitly states 'A DERIVED read; posts nothing', explains tenant isolation (not_found for other workspace), describes the running open quantity/value reconciliation, and notes that a just-created PO returns only its creation event. These details give the agent a clear model of the tool's side effects and edge cases.

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 a compact two-sentence block that is dense with specific information: event types, fields, running totals, derivation, and edge cases. No word is wasted, and the key purpose is front-loaded with 'complete PO history'. It earns its length by covering all essential aspects without repetition.

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 read-only, single-PO history tool with no output schema, the description is remarkably complete: it lists event types, returned fields (timestamp, actor, summary, amount, quantity, deep-link), running totals, derivation, tenant isolation, and initial-state behavior. The only missing piece is the purpose of the optional to_date/from_date parameters, which keeps it from a perfect score.

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 description coverage is 0%, so the description must compensate. It explains po_id (one PO) and workspaceId (tenant isolation), but makes no mention of to_date or from_date, which are present in the schema and presumably filter the timeline. Two of four parameters remain undocumented both in schema and description, which is a significant gap for an agent trying to invoke the tool correctly.

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 clearly specifies the tool returns the complete PO history for a single po_id, enumerating the exact event types (creation, I01-I04) and fields included. It is unambiguous about the resource and scope, and distinguishes itself from siblings by emphasizing the per-PO timeline rather than a list or current state.

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 provides clear context for when to use this tool: when you need the full ordered history of one PO (including revisions, receipts, allocations, and three-way matches). It does not explicitly name alternatives or exclusions, but the 'DERIVED read' and 'for one po_id' phrasing imply it is for read-only single-PO analysis, and the tenant isolation note clarifies cross-workspace behavior.

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