compare_recipe_options

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

With no annotations, the description carries the full transparency burden. It does disclose meaningful behavior: each route is solved end to end with the LP, and comparisons include raw resource per unit, whole buildings, net power, and byproducts needing an outlet. However, it omits potential side effects, computational costs, or how outputs are ordered, leaving some ambiguity for the agent.

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 concise, front-loaded with the main purpose, and uses line breaks for readability. Each sentence earns its place: the first defines the action, the second clarifies scope relative to a sibling, and the third details what the comparison includes. It could be slightly tighter, but it is well-structured and not wasteful.

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 complexity (8 parameters, no output schema, no annotations), the description is incomplete. It provides a high-level purpose but doesn't explain the output format, how routes are selected or ranked, or what the parameters control. The example ('Crude -> Alt HOR -> Diluted Fuel') helps, but operational details are missing, leaving the agent underinformed for correct invocation.

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 only 13% (1 of 8 params has a description), so the description must compensate. It fails to explain key parameters like 'outlets', 'allow_sinks', 'per_resource', or 'rate'. The mention of 'per resource' in the description is vague and doesn't clarify the parameter semantics, leaving most parameters underdocumented.

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 uses a specific verb ('Rank') and resource ('whole ROUTES to make an item') and clearly states the tool's scope: comparing routes by actual cost. It also distinguishes itself from the sibling tool 'alternates_for_item' by explicitly saying 'Not a recipe list', making its unique purpose clear.

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 names an alternative ('alternates_for_item') and states what this tool is not ('Not a recipe list'), providing a clear when-not-to-use signal. However, it lacks an explicit 'use this when' scenario, so it stops short of the full when/when-not contrast expected for a 5.

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