SAAX Protocol

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

No annotations are provided, so the description carries the burden. It discloses important behavior: rail-neutrality with settlementRail as metadata only and never a prerequisite, plus the returned fields (id format saax_<hash>, createdAt, status, settlementRail). It doesn't cover permissions/authorization or idempotency, which would be relevant for a create/persist operation.

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?

Four sentences, front-loaded with purpose, then rail semantics, then return values, then sequencing. Efficient and well-ordered, though the rail-neutrality point is repeated (title says 'rail-neutral', body reiterates it).

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?

Given 7 params with nested objects and no output schema, the description compensates well by naming the returned fields. It covers purpose, rail semantics, return shape, and next-step routing. Missing only edge cases like duplicate/idempotency behavior or auth requirements.

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 100%, so the schema already documents all 7 parameters including the nested terms/price/recoveryPolicy objects. The description adds value by clarifying the settlementRail semantics ('metadata only, unspecified is valid'), but otherwise the schema does the heavy lifting. Baseline 3 is appropriate.

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 ('Creates a governed commitment between a buyer and a seller') and names the persistence target (SAAX commitment store). This clearly distinguishes it from the read-only siblings like get_commitment and list_commitments.

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 says 'Call this BEFORE any payment flow' and directs the agent to get_commitment afterward for reading the manifest. Strong sequencing guidance, though it doesn't state when NOT to create a commitment (e.g., if one already exists for this pair).

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

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

No annotations exist, so the description carries the full burden. It usefully discloses a hard precondition (active SAAX Premium subscription), but says nothing about what happens on an invalid/expired proof, whether the call is read-only or mutating, or whether results are cached — significant gaps for a validation tool.

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?

Three short sentences, zero filler, with the core action front-loaded and the routing hint and precondition following in priority order. Nothing is repeated from the schema or title.

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 no annotations and no output schema, the description should at least hint at the validation result shape (valid/invalid, failure reason) and whether the operation has side effects. It covers the input-side precondition but leaves the entire result side unexplained.

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 100% and the schema already enumerates the AuthorityProof fields, so the baseline of 3 applies. The description adds no syntax, format, or value guidance beyond restating the proof/commitment pairing.

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 (validates) plus both operands (an authority proof against a commitment), which is precise enough that an agent can distinguish it from every sibling. It also explicitly separates itself from get_evidence_verification, the closest-sounding sibling.

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?

Names the alternative tool (get_evidence_verification) and the condition that selects it (evidence verification), and states the subscription prerequisite. It stops short of describing its own trigger conditions or any negative cases beyond the one alternative.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses the returned data scope (full object vs status-only), which is useful, but says nothing about error behavior (unknown ID), authentication requirements, or whether the manifest hash is verified. Adequate but not rich.

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?

Three tight sentences: purpose first, then payload contents, then two routing alternatives. No filler, front-loaded with the core action.

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?

Given no annotations and no output schema, the description adequately fills the gap by enumerating the returned fields and routing alternatives. Only missing piece is error/auth behavior for an unknown or unauthorized commitment ID.

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 100%, so the parameter's format is already documented in the schema (0x-prefixed or agent-id style). The description adds no new parameter syntax, but with full coverage and a single required param, the baseline is high.

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+resource ('Returns the full commitment object for a given commitment ID') and enumerates the fields returned (terms, state, manifest hash, evidence references). It explicitly distinguishes itself from siblings get_commitment_status and list_commitments.

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 states when to use this tool ('when an agent needs the complete commitment record') and names two alternatives with their selection conditions (status-only polling → get_commitment_status, listing → list_commitments). Nothing left to inference.

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

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

With no annotations, the description carries the full burden, and it does meaningful work: it discloses that this is a non-mutating status check rather than a POST, and that the response includes a next_action field driving retry/poll/stop decisions. It does not explicitly state the safety profile (read-only, side-effect-free) or confirm idempotency/polling semantics, which keeps it short of a 5.

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?

Four short sentences, each load-bearing: scope first, then the retry guidance, the next_action semantics, and the sibling routing. Nothing redundant and the operational guidance is 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?

For a narrow single-parameter status tool with no output schema, the description supplies what's missing: it explains the two things returned (lifecycle state and next_action) and how the caller should branch on them. Nothing an agent needs to invoke and interpret it correctly is absent.

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 the single commitmentId parameter is already fully documented in the schema. The description only refers to 'a given commitment ID' generically, adding no format, sourcing, or validation detail beyond what the schema provides. Baseline 3 applies.

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 ('Returns only the current lifecycle state for a given commitment ID') and scopes the response with 'only', explicitly contrasting against the broader sibling get_commitment. An agent can distinguish this from get_commitment without opening either 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?

Gives an explicit trigger ('Call this before retrying any commitment that timed out') with a rationale ('an unknown outcome is a status check, not another POST'), and names the alternative plus its condition ('For the full commitment record, use get_commitment'). When-to-use, when-not-to-use, and the alternative are all present.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses an authorization prerequisite (SAAX Premium subscription), but says nothing about whether verification mutates state, what a failed verification yields, or how results are returned.

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?

Three short sentences, front-loaded with the core purpose, then prerequisite, then sibling routing. Every sentence earns its place with zero 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?

For a four-required-parameter verification tool with no output schema and no annotations, the description covers purpose, prerequisite, and sibling routing, but omits what the verification result contains or how success/failure is signaled, leaving a gap the agent must discover at call time.

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 100%, so all four parameters (evidence, criterion, commitment, subscriptionEmail) are already documented in the schema. The description adds no format or interpretation detail beyond what the schema supplies, making the baseline 3 appropriate.

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 (verifies) and resource (external evidence against a commitment's acceptance criteria), which is precise enough to distinguish it from the other commitment tools. It also names the closely related sibling get_authority_validation and the domain in which that one applies.

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?

Gives a clear conditional route to an alternative ("For authority proof validation, use get_authority_validation") plus a prerequisite (active SAAX Premium subscription). It does not describe the full when-not conditions or the relationship to tools like get_commitment_status, so it falls short of exhaustive 5-level guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the return content (version, capability count, spec URL) and frames the call as a lightweight one-time overview, but does not explicitly state that it is read-only, side-effect free, or that it requires no authentication. Minor gaps for a trivial informational tool.

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-loads the return content, then gives the usage condition, then the three alternative routes. Every sentence earns its place with zero 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?

With no output schema present, the description compensates by naming the three returned values (version, capability count, spec URL), and it fully covers routing to sibling tools. Nothing an agent needs to invoke this 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify or compensate for. The description correctly implies a parameterless call with no inputs needed.

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 ('Returns the SAAX Protocol version, available capability count, and the URL to the specification'), and explicitly distinguishes itself from sibling tools get_routing_fee, list_capabilities, and ping. An agent can identify the tool's scope without opening the 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?

Gives an explicit use condition ('when an agent needs a one-time overview of the protocol') and routes three alternative needs to named siblings with the selecting condition for each (pricing, full capability list, liveness check). This is a textbook when/when-not/alternatives breakdown.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only lookup and hints at freshness ('current'), but does not state whether the schedule is cached or live, whether any auth is required, or what form the fee data takes. Adequate for a simple getter, but gaps remain.

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?

Three tight sentences with the core purpose and the pre-call timing front-loaded. The two trailing sibling pointers are slightly tangential to this tool's own use, but short and non-redundant.

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 zero-parameter, presumably read-only getter with no output schema, the description covers what it returns and when to invoke it. Only the behavioral profile (auth, freshness, return shape) is unstated, which is a minor gap at this complexity.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-related information is missing or misleading.

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 ('Returns the current routing fee schedule'), which is unambiguous and clearly distinct from siblings like get_protocol_info and list_capabilities. An agent can identify the tool's output without opening any 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 states when to call it ('before initiating a routing request to determine the expected cost') and routes adjacent needs to named alternatives ('For capability discovery, use list_capabilities. For protocol overview, use get_protocol_info'). Nothing is left to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the return content (capabilities plus supplier counts), which signals a read-only discovery operation, but it says nothing about auth requirements, result set size, or pagination for what could be a large capability index.

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?

Three short sentences, all front-loaded: what it returns, when to call it, then the two routing alternatives. Every sentence carries distinct information and none restates the title.

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 no output schema, the description usefully characterizes the return shape ('capabilities ... with supplier counts'), which is what an agent needs here. It is close to complete for a zero-parameter discovery tool, though it omits any note on result volume or ordering.

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 tool takes zero parameters, so there is nothing for the description to clarify beyond the schema; the baseline for a parameterless tool applies. The description's note about supplier counts per capability is relevant framing but is not parameter guidance.

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 ('Returns the capabilities currently indexed by the SAAX Router') plus the payload detail ('supplier counts per capability'). It also explicitly separates itself from the two nearest siblings, get_routing_fee and get_protocol_info, so an agent can disambiguate without opening schemas.

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?

'Call this to discover what can be routed' gives the triggering condition, and it names two alternatives with the exact condition that selects each ('For pricing of a specific capability, use get_routing_fee', 'For protocol overview, use get_protocol_info'). Nothing about when-to-use is left to inference.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose a real prerequisite (an active SAAX Premium subscription), but that same constraint is already duplicated in the schema. It says nothing about result volume, ordering, pagination, or failure modes when the subscription is inactive, which matters for a list endpoint.

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?

Three short sentences, all front-loaded: purpose first, then the premium prerequisite, then the alternative routing. Every sentence earns its place with no 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?

For a single-parameter list tool with no output schema, the description covers what it returns, the auth prerequisite, and the sibling routing. It could note ordering or pagination behavior for a list endpoint, but no essential calling information 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% for the single subscriptionEmail parameter, so the schema already documents it fully, including the Premium requirement. The description adds no syntax, format, or validation detail beyond the schema, so the baseline 3 applies.

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 ('Returns all commitments associated with a subscription email') and scopes it to a subscriber. It explicitly distinguishes itself from get_commitment and get_commitment_status, so an agent can select it without opening sibling schemas.

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 calling condition ('Call this to retrieve commitment history for a subscriber') and names two alternatives with the exact situations that select them: get_commitment for a single ID, get_commitment_status for status-only checks. Nothing is left to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the core behavior ('lightweight liveness response') and implies a safe, non-mutating read, but does not explicitly state idempotence, side-effect absence, auth requirements, or output format. For a liveness probe this is mostly sufficient, though not fully explicit.

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?

Three short sentences, front-loaded with purpose before exclusions. Every sentence earns its place: behavior, positive usage, and negative usage with named alternatives.

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 zero-parameter liveness tool, the description supplies purpose, usage boundaries, and alternatives. The only minor omission is a precise description of the response shape, but 'lightweight liveness response' is adequate given the tool's simplicity.

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?

There are zero parameters and the schema is an empty object, so there is no parameter semantics for the description to add. The baseline for a zero-parameter tool is 4.

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 ('Returns a lightweight liveness response') and scopes it to reachability testing. It explicitly distinguishes itself from sibling discovery, capability, and pricing tools by naming the alternatives.

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?

Tells the agent exactly when to call this tool (verify the endpoint is reachable) and when not to (discovery, capability listing, pricing), and names the three alternative tools. This is a complete routing instruction.

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

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

No annotations are provided, so the description carries the full disclosure burden. It usefully clarifies that payment/commitment creation is not performed here, but never states whether routing itself has side effects (does it create a routing record?), what authorization is needed, or whether results are persisted. That leaves a meaningful gap for a call that sits adjacent to commitment creation.

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?

Three short sentences, each doing distinct work: what it does, the excluded HTTP path, and the prerequisite/follow-up tools. The primary function is front-loaded with zero 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?

There is no output schema, so the description must characterize the return value, and it does so at a high level ('ranked supplier matches') plus the next step for commitment lookup. It could say more about what ranking fields come back or how many matches are returned, but nothing needed to invoke the tool 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 description coverage is 100%, so budget, deadline, and capability are already documented with types and units (USDC, seconds from now). The description adds no additional parameter meaning beyond calling it a 'capability request', so the baseline of 3 applies.

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 ('Submits a capability request and returns ranked supplier matches') and explicitly draws the boundary that commitment creation with payment happens via the HTTP POST /route endpoint rather than this tool. An agent can distinguish it from create_commitment without opening either 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?

Gives explicit ordering guidance ('Use list_capabilities first to discover available capabilities') and names the follow-up alternative ('For commitment lookup after routing, use get_commitment'). It also states the when-not case: commitment creation with payment is out of scope for this tool.

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