loan_terms_preview

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

The description discloses that it's informational only and not financial advice, and that it returns 404 for cards not on the free board. It also mentions it provides a worked derivation with steps and links. However, it doesn't mention side effects (it's read-only) or rate limits, but for a simple preview tool, this is adequate. No annotation contradicts.

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 quite verbose, with repeated mentions of 'FREE', the URL, and the paid quote. It could be more succinct, but the core information is present and front-loaded. The 'Use this when' sentence is helpful.

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 the tool's simplicity (2 params, no output schema), the description covers the purpose, use case, and key behavior. It mentions the free board limitation and the alternative paid quote, which is useful context. It could be more explicit about the exact output format, but not necessary.

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 description adds value for term_days by specifying allowed values (7, 14, or 30), which is not in the schema. It does not elaborate on product_id, but that is likely straightforward. The schema has a default for term_days, but the description clarifies the valid range.

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 tool's function: it derives safe lending terms for a trading card on the free board, with a specific process (value → calibrated 99% tail → liquidation buffer → liquidity cap → max LTV). It distinguishes itself by noting it's for the free board and that off-board cards return 404, differentiating from paid quote.

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 explicitly says 'Use this when: an agent wants collateral math for a card, or to explain how the Loan-Terms Oracle derives an LTV before paying for a full quote.' It also mentions the 404 behavior for off-board cards, providing clear conditions for when to use this tool.

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