Create Purchase Requisition

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

The annotation declares destructiveHint=true, which signals this is a write operation. The description adds meaningful behavioral context: the operation is append-only, does NOT authorize spending, and creates an independent human-escalation request. This goes beyond what the annotation provides by clarifying the non-authorization semantics, which is critical for safe use. However, it doesn't disclose what happens on duplicate entries, whether the human escalation is blocking, or what the cryptographic binding implications are beyond what the schema's toolName/toolInput descriptions mention. With a destructiveHint present but description adding semantic nuance, score 3 is appropriate.

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?

Two sentences with zero waste. The first sentence states the core function, and the second overrides a dangerous potential misconception ('does not authorize spending'). Every word earns its place. It could add a bit more about when to use it, but for the length it has, it's efficient and front-loaded.

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?

This is a complex tool (10 params, 8 required, nested objects, cryptographic binding semantics) with no output schema and low schema description coverage. The description is too brief to fully equip an agent for correct invocation. It explains the overall purpose and a critical safety caveat, but doesn't explain the requisition lifecycle relationship (how reserve/settle interact), what the expected outcome is (no output schema), or the evidence structure. Given the complexity, a bit more detail is warranted, though the critical safety distinction is present.

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 only 30% (3 of 10 params have descriptions: toolName, toolInput, sourceMessageId), which is below the 50% threshold, so the description must compensate. The description itself adds no parameter-level detail, leaving the meaning of amountUsd, vendor, purpose, evidence, taskId, ttlMs, and idempotencyKey entirely to the schema's type definitions. The schema describes the crypto-binding semantics for toolName and toolInput already, so those params are covered. The description could have explained the evidence array's role in supporting the escalation, but the gaps in parameter semantics remain unaddressed.

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 states a specific verb+resource ('create an append-only purchase requisition and independent human-escalation request') and clarifies the scope ('does not authorize spending'). It distinguishes from sibling tools like settle_purchase_requisition and request_human_escalation, though it doesn't explicitly name them as alternatives. The key differentiator—that this is append-only and does not authorize spending—is valuable given the many related purchase requisition tools.

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 notes the tool is append-only and escalates to humans but does not explain when to use this vs. siblings like reserve_purchase_requisition, settle_purchase_requisition, or request_human_escalation. Given the large cluster of related purchase tools, explicit guidance on when to choose this one would be highly valuable. The no-authorization clarification helps but doesn't cover the decision boundary between this and the other requisition lifecycle tools.

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