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 disclose the key behavioral fact that this is a paid operation at $3.49 USDC plus the 50-contract ceiling. It omits whether payment is still consumed on partial failure, retry/idempotency behavior, and latency for a 50-document batch.

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?

A single sentence that front-loads the two decision-critical facts: the price and the 50-contract scope, followed by the output content. No filler whatsoever.

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 and no annotations, the description usefully enumerates the returned summary types (ranked risk, renewal, penalty, obligation, payment terms) and the price. Only the payment lifecycle and batch failure semantics are left unaddressed, which the schema partially covers.

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 50% and the description adds no parameter detail beyond the implicit 50-item cap already enforced by maxItems. The paymentSignature challenge-then-retry flow is documented in the schema, not the description, so the description neither compensates for nor duplicates the coverage gap.

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 (scan) and resource (contract portfolio) with an explicit scope cap of 50 contracts and a named price. It clearly distinguishes itself from single-contract siblings like analyze_contract_risk, but it never names scan_contract_portfolio_200 as the alternative for larger portfolios.

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?

There is no when-to-use guidance: nothing says when a portfolio-level scan beats individual calls to triage_contract or extract_contract_obligations, and no condition selects this tool over the 200-contract variant. The price is stated, but no prerequisite or eligibility context is given.

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