returncheck

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

With annotations completely absent, the description carries the full burden, and it does a good job: it prominently discloses the critical guardrail 'Never invents: returns UNKNOWN instead of guessing,' and describes that the verdict includes a verbatim policy clause, source URL, and confidence score. This is strong behavioral transparency, though it does not describe network-fetch side effects or timeout behavior, keeping it just short of a 5.

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 just two sentences, very efficient, and front-loaded with the core question ('can product actually be returned'). Every sentence earns its place: the first defines its purpose, the second defines its inputs and outputs, and the third (the guardrail) is concise. There is no fluff or repetition.

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 no annotations, the description manages to be quite complete: it fully defines the verdict categories and output components. However, it does not mention the optional supporting fields such as purchase_date, delivery_date, reason, merchant, or page_text/page_html, and it also does not say that page_html can bypass fetching. Since the existing schema descriptions fill in these gaps, the tool definition is mostly complete but not flawless.

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 main description adds only minimal meaning over the schema: it mentions product URL, buyer country, and item condition, but these are already covered by schema descriptions or enums. Six of ten parameters have schemas already described, and the description omits useful guidance about optional parameters like reason, merchant, seller_name, delivery_date, and page_text/page_html (though page_html has a comprehensive schema description). For 60% schema coverage, the description partially compensates but not fully.

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 has a crystal-clear verb and resource: it answers a specific question about whether a product can be returned. It goes further by enumerating the exact verdict categories (YES / YES_WITH_CONDITIONS / NO / UNKNOWN) and the inputs (product URL, buyer country, item condition). This leaves no ambiguity about what the tool does, and sibling differentiation is not needed because no siblings exist.

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 clearly sets the usage scenario: use this when you need a verified return-eligibility verdict for a specific product, and it tells the agent what to send (product URL, buyer country, optional condition). It does not explicitly articulate 'when not to use' or alternative paths, but given there are no sibling tools, the context provided is sufficient and clearly scoped.

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