assess_offer_readiness

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

With annotations declaring readOnlyHint=false and destructiveHint=false, the description usefully explains why a read-looking assessment is a mutation: it 'creates a metered asynchronous job and may retain delivery state.' Disclosing that the call is metered (cost-bearing) and async is exactly the kind of context annotations cannot convey, and the negative list ('No fetching, inference, FAHCE, approval or payment') bounds side effects.

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 key fact (job, not report) is front-loaded and the sentences are information-dense, but the description repeats itself: 'without revising seller terms' and 'Does not revise seller terms' say the same thing twice. Terms like 'FAHCE' are used without explanation, adding noise rather than signal.

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 an async, metered job tool with an output schema, the description covers the essential contract: it returns a handle, the report arrives via get_result, and some outcomes may come back as a resumable manifest. Combined with the idempotency and retry notes in the schema, an agent has enough to call it correctly, though the undefined jargon leaves a small gap.

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?

Both parameters are fully documented in the schema (100% coverage), including the retry/request_id reuse contract, and the description only alludes to session_id via 'your retained session.' Nothing in the description adds syntax or constraints beyond the schema, so the baseline of 3 applies.

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 operation: a deterministic readiness assessment over the caller's retained session, and explicitly separates itself from get_result by saying it 'Returns a job, not the report' which must be polled. The scope exclusions ('Not seller certification or commercial clearance') sharpen the boundary. It stops short of distinguishing itself from export_offer, so an agent choosing between those two still has to infer.

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?

It provides a clear downstream step ('poll get_result for signed readiness JSON'), which is real usage guidance, and it names what the result is not. However, there is no explicit statement of when to call this versus export_offer or get_status, and no stated prerequisite such as 'call start_session first' beyond the implicit 'your retained session'.

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