LedgerProof LAIN — Verified Evidence for Agents

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

With no annotations, the description fully discloses the behavior: it is a read-only listing with no side effects. It specifies the exact fields returned (capability ids, input schemas, pricing, environments, settlement rule), providing complete transparency.

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 single, well-structured sentence that front-loads the main action ('List everything') and concisely enumerates the returned fields. No unnecessary words.

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 lacking annotations and output schema, the description is entirely self-contained. It fully explains what the tool returns and the context (LAIN capabilities), making it complete for an agent to understand.

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 has zero parameters with 100% schema coverage, so the description naturally adds no parameter details. This is optimal for a parameterless tool.

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 uses the verb 'List' with the resource 'everything the LAIN sells', clearly defining the tool's action and scope. It differentiates from sibling tools 'get_job' and 'request_capability', which serve different purposes.

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 clearly states what the tool does, and the context signals (sibling tools) imply that this is the appropriate tool for listing capabilities. No explicit when-not or alternative guidance is needed because the purpose is distinct and well-defined.

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?

Despite no annotations, the description discloses that for paid checkout jobs, polling triggers settlement and captures the charge, which is a critical side effect beyond simple polling. This adds significant value beyond the default behavior inference.

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 two sentences, each adding essential information. First sentence states the basic action, second provides critical nuance. No redundant words.

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 simple one-param tool with no output schema, the description covers the main behavior, special case for paid checkout, and implied output. It lacks details on error handling or timeout behavior, but is mostly complete for its 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 single parameter 'job_id' has no schema description, and the description only mentions 'by id' without specifying format, source, or constraints. Schema coverage is 0%, so the description fails to compensate with meaningful param details.

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 states the verb 'poll' and the resource 'job by id', distinguishing the tool's primary function. It also specifies a special behavior for paid checkout jobs, making the purpose unambiguous. Sibling tools are unrelated, so no confusion.

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: polling jobs, especially as a settlement trigger for paid checkout jobs. It does not explicitly state when not to use it, but given the sibling tools have different purposes, the guidance is adequate.

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 full burden. It discloses that test uses simulated money, live is a real purchase with immediate proof and a Stripe URL, and that the Authorization header passes through. It does not mention reversibility or side effects, but the key behaviors (payment required for live) are clear.

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 moderately concise, covering essential points in a few sentences. It front-loads the core action ('Buy a capability.') and then provides details in a logical flow. Some density is acceptable given the number of parameters, but it could be slightly more structured.

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?

The description explains the test/live distinction and mentions return behavior for live (anchored proof + Stripe URL). However, for test environment the response is not described, and many optional parameters have no guidance. With 20 parameters and no output schema, more completeness is needed.

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 only 5% (one parameter described). The description adds meaning for capability (pattern and hash format), environment (default 'test'), and mentions relevant parameters (inputs_hash, outputs_hash, state_hash, objective, budget). However, many parameters (model, action, settlement, idempotency_key, etc.) are left unexplained, so compensation is partial.

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 starts with 'Buy a capability.' and clearly explains the tool's purpose: to purchase a capability by providing capability ID, action, and hashes. It distinguishes between test and live environments, making the purpose specific and unambiguous. Sibling tools are different (discover_capabilities, get_job), so no confusion.

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 guidelines on when to use test (simulated money) vs live (real purchase with Stripe checkout). It mentions the default environment and how to pass the Authorization header for identity settlement. However, it does not explicitly state when to use this tool over siblings, though the context is sufficient.

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