Pre-deal clearance verdict (free)

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

The description goes far beyond the annotations by disclosing the 5-per-24-hour quota, the exact error code on exhaustion, the two verdict_source modes and why the agent should relay evidence_gaps, and the fact that the response carries a legal disclaimer that must be passed on. It also clarifies that this is decision-support, not a clearance or legal advice. Annotations are consistent with this mutating-but-not-destructive profile, so no contradiction exists.

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 long but every sentence carries operational value: main result first, then quota semantics, then output fields the agent must relay, then required-input handling, then the alternative. There is no filler or repetition of schema content. Given that no output schema exists, this density is justified and well-organized.

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 tool with no output schema and six parameters, the description covers all critical context an agent needs: what the verdict contains, how quota errors manifest, what fields to relay to the user, which inputs are mandatory, and which sibling tool to use for the higher-tier version. Nothing essential for correct invocation 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 already 100%, so the baseline is 3. The description adds meaningful semantic context beyond the schema: it enumerates the required inputs, explains that counterparty_role has no safe default because the verdict differs by side, and warns that the endpoint rejects calls missing required fields. This is a genuine supplement to the schema rather than mere repetition.

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 names the specific operation (OilFlow Pre-Deal Compliance check) and the exact outputs (probability 0-100, verdict tier, blockers, restructure suggestion, receipt_id, verify_url, verdict_source, evidence_gaps). It also differentiates itself from the sibling predeal_check by explicitly labeling this the free, quota-limited version. An agent can immediately tell what this tool does and how it differs from nearby tools.

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 gives explicit when-to-use guidance: use this for the free quota-limited verdict, and names the alternative predeal_check for the keyed version with no daily cap and full input set. It also instructs the agent to ask the user for missing required inputs rather than guessing, and clarifies that the demo_limit_reached error means quota exhaustion, not an outage. This leaves no ambiguity about when to invoke this tool versus alternatives.

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