scaleRecipe

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

Annotations already declare readOnlyHint and idempotentHint, so the bar for additional disclosure is lower. The description adds two important non-obvious behaviors: macro-target scaling requires precomputed current totals because the server does not infer them, and discrete-unit amounts are reported as fractions rather than rounded. These are directly useful for predicting tool behavior.

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 three sentences with no filler. The first sentence states the purpose, and each subsequent sentence adds a distinct, valuable caveat: the prerequisite for macro scaling and the rounding behavior for discrete units.

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 rich input schema and existing output schema, the description covers the most critical non-obvious constraints: needing current totals from computeBatchMacros and never rounding discrete units. It does not enumerate the three scaling modes, but the schema fully specifies them, so an agent has enough context to invoke the tool correctly.

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 description coverage is 0%, and the description does not compensate by explaining the `by` parameter's three allowed kinds or the `ingredients` array structure. It only mentions 'raw ingredient list' and 'current totals,' which are already present in the schema, so it adds minimal parameter meaning beyond what structured fields provide.

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 and resource: 'Scale a raw ingredient list.' It clearly names the tool's core action and even calls out the macro-target mode, but it does not explicitly distinguish itself from sibling scaling tools like portionBatch or planBatchSize.

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 useful contextual guidance for macro-target scaling by pointing to computeBatchMacros and warning that the server does not infer recipe contents. However, it does not explain when to use factor or targetServings modes, nor does it contrast the tool with sibling scaling alternatives like portionBatch or planBatchSize.

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