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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that the output is an unsigned blueprint, that the user must sign and broadcast, that Aletheia holds no keys, and it explains the auction mechanic where lenders bid down from max_repayment. It also reveals that the tool includes the collateral approval step, which is non-obvious behavioral information.

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 four compact paragraphs, each carrying distinct value: purpose, user control/limitations, key auction mechanic, and security/user responsibility. The most important information is front-loaded, and no sentence feels redundant 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?

Given 10 parameters, no output schema, and no annotations, the description covers all critical aspects: what the tool does, what the user must decide, the risky parameter behavior, the returned output nature, and the wallet custody model. It is fully sufficient for an agent to decide whether and how to invoke this 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema, especially for max_repayment ('your worst acceptable price — set it too low and the auction may attract no bids') and clarifies the role of bid_step among the settable terms. It doesn't need to relist every parameter, but the added auction dynamics explanation improves parameter understanding.

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: 'Builds an unsigned transaction blueprint for creating a borrow auction' and clarifies the inclusion of the prerequisite collateral approval. This clearly distinguishes it from sibling calldata builders like prepare_bid_calldata and prepare_repay_loan_calldata, so an agent can tell what this tool is for without needing to open 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?

The description establishes when to use the tool: when creating a borrow auction where you post collateral and ask lenders to compete. It also states what it does not do ('does not propose terms, rates or a loan size'), which helps set expectations. However, it does not explicitly name alternatives or state when not to use it, though the sibling names make the contrast fairly obvious.

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