ReciPal MCP by usefulapi

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

Annotations already declare destructiveHint=true, non-idempotent, and write access, so the safety profile is covered. The description adds non-obvious downstream effects — the change alters the recipe's nutrition, label, and cost — plus the precedence rule that total_grams overrides unit and quantity. It is silent on duplicate-line behavior, which matters for a non-idempotent write.

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?

One front-loaded sentence with a tightly scoped parenthetical, followed by the endpoint. Every clause (write marker, unit sourcing, override rule, downstream effects, path) carries information an agent needs.

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 6-parameter write with no output schema, the description covers purpose, valid value sourcing, override semantics, and downstream impact. The only meaningful gap is what happens on a duplicate ingredient line, which is relevant given the non-idempotent annotation.

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 100%, so all six parameters are already documented. The description contributes the cross-parameter precedence rule (total_grams overrides unit and quantity) and directs the agent to where valid unit values come from, which the schema does not state; otherwise the parameter guidance is schema-duplicated.

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?

Opens with an explicit verb+resource+scope: 'WRITE: add an ingredient line to a recipe.' The sibling set contains update_recipe_ingredient and remove_recipe_ingredient, and this phrasing makes clear it appends a new line rather than modifying or deleting one.

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 gives two distinct calling modes (by unit/quantity vs. total_grams) and routes the agent to the right reader tools to obtain valid units ('see units_and_grams from recipal_get_recipe_ingredient or valid_units from recipal_get_ingredient'). It does not say when to prefer this over recipal_update_recipe_ingredient or what to do if the ingredient is already on the recipe.

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

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

Annotations already declare readOnly=false, destructive=true, and idempotent=false, so the safety profile is covered structurally. The description adds genuinely non-obvious behavior: the record is private to the account, and food/non_food are immutable after creation — a constraint an agent could not infer from annotations or schema. It does not mention rate limits, auth scopes, or whether a partial failure rolls back.

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?

Front-loads the operation type and core purpose in the first clause, then layers food vs non-food branching and the immutability warning. The single dense paragraph is slightly run-on across the food/non-food split, which would read better as two sentences, but no sentence is filler.

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 11-parameter tool with nested objects, 1 required field, and no output schema, the description covers the branches and order-of-operations an agent needs. The one real gap is that it never says what comes back on success (presumably the created ingredient id), which matters for a create call the agent will likely chain into create_ingredient_cost.

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 100%, so the baseline is 3; the description earns an upgrade by adding cross-parameter semantics the schema cannot express — that measures must be populated before a custom volume unit can be used in nutrition_unit, and that nutrients are entered per nutrition_quantity x nutrition_unit. It stops short of 5 because the lengthy nutrient list itself is left entirely to the schema.

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 verb and resource ("create a custom ingredient") plus a distinguishing scope ("private to your account"), which separates it from recipal_create_ingredient_cost, recipal_add_recipe_ingredient, and recipal_update_ingredient. The leading "WRITE:" marker makes the operation class immediately obvious.

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?

Gives concrete conditional guidance: food ingredients need nutrition_unit/nutrition_quantity and required nutrients, while non-food items need food=false plus one of five non_food enum values. It also states a prerequisite ("for units beyond gram/oz/lb/kg add them in measures first"). It falls short of 5 because it never names a sibling to use instead, e.g. update_ingredient for modifications or create_ingredient_cost for costing.

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

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

Annotations declare the write/destructive/non-idempotent profile, and the description goes well beyond them by disclosing the cascade: 'Changes the cost of every recipe using the ingredient from that date.' It also explains the active-cost resolution rule (latest effective_at not after the date) and the one-cost-per-ingredient-per-date constraint, which is exactly the sensitivity an agent needs before mutating.

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?

Front-loaded with the operation class, then scope, then side effects, then the exclusion, then the endpoint. Five short clauses, no filler, and no sentence that could be deleted without losing 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 a destructive 6-parameter mutation with no output schema, the description covers scope, side effects, and the key restriction. What is missing is only the return value (whether the created cost id comes back) and error behavior on the subrecipe case.

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 100%, so baseline would be 3, but the description adds real semantics: 'price and shipping are per quantity x unit' explains how three separate numeric fields combine, which the schema alone does not. The effective_at resolution rule likewise clarifies a parameter the schema only labels as a date.

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?

Specific verb+resource: 'add a price for an ingredient' keyed to effective_at, with the 'WRITE:' prefix making the operation class unmistakable. The effective-dating framing implicitly separates it from update_ingredient_cost, but no sibling is named outright, so an agent must infer the create-vs-update boundary.

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?

Gives a hard exclusion ('Not allowed for subrecipe ingredients') and explains that the cost applies from a date forward, which tells the agent when this tool is the right choice. It stops short of explicitly routing to recipal_update_ingredient_cost or recipal_list_ingredient_costs for existing/historical costs.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the description doesn't need to restate the write semantics. It adds genuinely new context: the call creates a record in the caller's ReciPal account, consumes a slot in the plan's recipe allowance (a quota/cost constraint not in any structured field), and maps to POST /recipes. It stops short of warning about retry duplication despite idempotentHint=false, which is the one behavioral note an agent could still use.

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?

Two sentences plus an endpoint, with the operation class ('WRITE:') front-loaded and the alternative-path guidance immediately after the primary action. No restatement of the title, no filler, and the quota note is compressed to a single clause.

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 17-parameter, nested-object mutation the description covers the essentials: it is a shell-creating write, everything is optional, and it costs a plan slot. The remaining gap is the return value — there is no output schema, so the agent is not told whether the created recipe's ID comes back or whether it must call recipal_get_recipe / recipal_list_recipes afterward to obtain it.

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 100% with 17 well-documented properties, so the schema carries the burden and baseline would be 3. The description adds one materially useful fact the schema cannot convey: 'All fields are optional' (required=[]), confirming an empty body produces a valid empty recipe — that is exactly the decision an agent needs before calling.

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 verb and resource ('create a new, empty recipe') plus the WRITE prefix marking it as a mutation. It explicitly distinguishes itself from two siblings by name (recipal_add_recipe_ingredient, recipal_create_recipe_from_ingredients), so an agent can route correctly without opening any schema.

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?

Gives concrete when-to-use-this vs. when-to-use-the-alternative guidance: use this for the shell, then recipal_add_recipe_ingredient for lines, or skip straight to recipal_create_recipe_from_ingredients to do both. That is explicit alternative routing, not inference.

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

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

Annotations already declare write, destructive, non-idempotent, and openWorld behavior. The description adds the 'WRITE:' prefix, that a record is created, and the endpoint, but does not disclose auth requirements, rate limits, or what happens on duplicate/invalid ingredient ids — gaps that matter for a destructive mutation.

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?

Four short sentences, front-loaded with the 'WRITE:' marker and the core action. Every sentence carries useful information (action, required ingredient format, optional fields reference, endpoint) with no filler.

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 18 parameters with 100% schema coverage and full annotations, the description covers the high-level action, required ingredient structure, optional fields, and endpoint. It omits what the call returns (no output schema exists), which would be the one missing piece for a fully complete definition.

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 100%, so the schema already documents all 18 parameters in detail. The description repeats the required 'ingredients' format (ids plus grams) and points to recipal_create_recipe for optional fields, which is mildly helpful but adds little beyond the schema.

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 verb and resource: 'create a new recipe and its ingredient lines in one call.' The phrase 'in one call' and the cross-reference to recipal_create_recipe hint at differentiation from the sibling, but the definition never explicitly contrasts the two tools' roles.

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?

Usage is implied by 'in one call' and the reference to recipal_create_recipe for optional fields, but there is no explicit statement of when to prefer this over recipal_create_recipe plus recipal_add_recipe_ingredient, nor any exclusions or prerequisites.

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

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

Annotations already cover write/non-idempotent/destructive, and the description adds real value: the live reference semantics ('later changes to the recipe flow through to the ingredient'), the empty-recipe failure mode, and the POST path. It does not explain what the destructiveHint refers to (what gets removed or unlinked), leaving one gap.

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?

Two tight sentences plus an endpoint, front-loaded with a WRITE: marker so the operation type is seen first. Every clause carries information: purpose, propagation behavior, failure condition, return value.

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?

With no output schema, the description usefully says it returns the new ingredient, and it covers preconditions and side effects. What is missing is a clarification of the destructive annotation's implication and any indication of what the returned ingredient contains.

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 100% with a single, self-explanatory recipe_id, so the schema already does the work. The description adds no format or constraint detail beyond what is in the schema, which is the baseline case.

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 verb and resource plus the mechanism: convert a recipe into an ingredient that carries nutrition, costing and ingredient list. The 'subrecipe' framing and live-link behavior make it distinguishable from recipal_create_ingredient, but no sibling is named explicitly.

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 purpose clause ('so it can be used inside other recipes') implies the use case, and the precondition 'Fails if the recipe is empty' is stated. It stops short of naming when to prefer this over create_ingredient or create_recipe_from_ingredients.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful piece of context beyond that — the inventory-plan prerequisite — plus the underlying endpoint, but says nothing about not-found behavior or what the row contains.

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?

Three terse fragments, front-loaded with the resource and scope, then the prerequisite, then the endpoint. Nothing is padded and no sentence is wasted.

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 one-parameter read with annotations carrying the safety profile and no output schema, the description covers the essentials plus a prerequisite an agent would otherwise miss. Only the failure/empty-result behavior is left unaddressed.

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 100% and the single parameter is already documented as 'Finished good row id.' with a positive-integer constraint. The description's 'by id' adds no format, range, or sourcing guidance beyond the schema, so baseline 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 verb (implicitly 'get') and resource ('one finished-goods stock row') scoped by id, which clearly separates it from recipal_list_finished_goods. The scope word 'one' is doing the sibling-differentiation work, though it never names the list tool explicitly.

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?

'Needs an inventory plan' implies a prerequisite context for use, but the description never states when to pick this over recipal_list_finished_goods or what to do if the id is unknown. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds genuine context beyond them: that the resource may be owned or public, and exactly which fields come back. It says nothing about not-found behavior, which keeps it out of 5 territory.

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?

Two short sentences, zero filler, and the payload enumeration is front-loaded ahead of the endpoint path. Every clause carries information an agent can act on.

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?

With no output schema, the description correctly compensates by enumerating the returned fields, and the single required param is fully documented in the schema. Only the ownership/public access distinction and failure modes are left slightly thin, which is minor for a read-only lookup.

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?

Only one parameter and schema coverage is 100%, with 'ReciPal ingredient id' already documented in the schema. The description adds no syntax, sourcing hint (e.g. where to get the id from list_ingredients), or constraints, so the baseline 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?

Specific verb+resource ('One ingredient in full') plus the actual payload contents (allergens, ingredient-list text, custom units, nutrients per 100g), which clearly separates it from recipal_list_ingredients and recipal_get_ingredient_cost. It never names a sibling explicitly, so differentiation is inferential rather than stated.

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 'in full' phrasing implies this is the detail-fetch counterpart to the list/cost siblings, and 'yours or a public one' hints at the access scope. But there is no explicit 'use this when…' statement or named alternative, so the agent must infer when to pick this over recipal_list_ingredients.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety behavior is covered. The description adds the underlying GET endpoint path, which is useful mapping context, but it does not mention error behavior such as a missing id or permissions.

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?

Two short sentences, zero waste, and the core lookup behavior is front-loaded. The endpoint path is compact and does not distract from the purpose.

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 simple one-parameter read tool with full schema coverage and annotations covering safety, the description is largely complete. It implies the return value ('one ingredient cost entry') and does not need an output schema explanation, though more detail about not-found behavior could help.

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 schema has 100% description coverage for the single ingredient_cost_id parameter, so the baseline is 3. The description only restates that the lookup is 'by id' and adds no additional meaning beyond the schema.

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 states a specific retrieval action for a single ingredient cost entry by id, which clearly distinguishes it from list-oriented siblings like recipal_list_ingredient_costs. It is clear but does not explicitly name the alternatives or explain the scope difference in prose.

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?

Usage is implied by 'by id': fetch one entry when you know its identifier. There is no explicit statement of when to use this versus list_ingredient_costs or get_ingredient, so the agent must infer the selection criteria.

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

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

Annotations already cover readOnly/destructive/openWorld, so the description's added value is the returned field set (quantity, unit, weeks remaining, reorder guideline, on-hand value) and the inventory-plan prerequisite. Error behavior and what happens for a missing/nonexistent id are not addressed.

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?

Three compact fragments, front-loaded with the resource and id lookup. The parenthetical field list is dense but earns its place by substituting for a missing output schema.

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?

With no output schema, listing the returned fields is exactly what the description should supply, and the prerequisite note is useful. Only the ambiguity of the plan prerequisite and absence of error semantics keep it from a 5.

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?

Only one parameter and schema coverage is 100%, with the schema itself stating 'Inventory row id.' The description's 'by id' adds nothing beyond that, so baseline 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 verb and resource ('One raw-material stock row by id') and enumerates the returned fields, which clearly separates it from recipal_list_inventories. It does not explicitly name the list sibling as the alternative, so a 5 is not warranted.

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?

'Needs an inventory plan' signals a prerequisite, but the phrasing is terse and ambiguous - it is unclear whether the plan feature gates the call or is merely context. No alternatives or when-not-to-use conditions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the response is a saved configuration plus computed claims and a per-language ingredient list, which is useful behavioral context, but says nothing about failure modes (invalid token, unsupported format) or whether an unspecified format falls back to the saved one.

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?

Three compact sentences, front-loaded with what is returned, then token sourcing, then the optional override. There is mild redundancy with the schema's parameter descriptions, but no filler or repetition of the title.

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?

With no output schema, the description carries the burden of describing the return payload and does so concretely (settings, claims, ingredient list per language). For a two-parameter read tool this is close to complete; only error behavior and the default when result_format is omitted are left unstated.

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 100%, so both parameters are already documented in the schema, including the token's origin and the format example. The description largely restates those facts ('token is the last part of the recipe's primary_label path', 'compute claims ... for another format'), adding a concrete path template but no new semantics such as what happens when result_format is omitted.

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 exact resource: saved nutrition-facts label settings (format, visible rows, styling) plus computed claims and per-language ingredient list. It is clearly a read of a label definition, distinguishing it implicitly from recipal_start_label_render and recipal_get_label_render_status by returning settings rather than render state. The verb is only implied via the trailing 'GET /labels/{token}' rather than stated up front, keeping it from a 5.

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?

There is no explicit guidance on when to call this versus recipal_get_label_render_status or recipal_start_label_render, which are the obvious neighboring tools in a label workflow. The only usage-like hint is that the caller may optionally compute for another format, which describes a parameter rather than tool selection.

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

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

Annotations only cover the read-only/safety profile; the description adds genuinely new behavior: the four status values, that url is a temporary presigned download link only when ready, the recommended polling cadence, and that polls are rate-limited against the weekly quota. That is substantial context beyond the structured fields.

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?

Three tight sentences front-loaded with the resource and statuses, then operational guidance, then the endpoint. No filler; every clause carries information.

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?

No output schema exists, yet the description names the key return fields (status values, url meaning) and the rate-limit caveat, which is everything an agent needs to poll correctly and avoid quota waste.

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?

With one parameter and 100% schema description coverage, the schema already documents token and its source. The description echoes the origin tool but adds no format, constraint, or handling detail beyond what the schema supplies, so the baseline 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 verb and resource (get label render status) plus the exact status set (waiting, processing, ready, error), and ties it to the sibling that creates the token. An agent can immediately distinguish this polling tool from recipal_start_label_render.

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?

Clear precondition: use after recipal_start_label_render with the returned token, poll roughly once a second, and note that each poll consumes the weekly request limit. It lacks an explicit 'stop polling when ready/error' or when-not statement, so it falls just short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description earns credit by disclosing the shape of what comes back (costs broken into ingredient vs packaging/labor/overhead, per-serving nutrition), which matters because there is no output schema. It omits error behavior for an unknown recipe_id, which keeps it below 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?

One dense sentence that front-loads the core promise ('One recipe in full') and then lists the payload, followed by a compact endpoint marker. No filler 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 one-parameter read tool with no output schema, the field enumeration supplies what the agent needs to decide whether this call returns the data it wants. Only missing piece is failure behavior when the id does not exist.

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?

A single parameter with 100% schema description coverage ('ReciPal recipe id.'), so the schema already carries the load. The description adds no format or sourcing hint for recipe_id, so baseline 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 retrieval action plus an enumerated payload: yield, servings, allergens, costs, ingredient list, tags, label path, nutrition. Implicitly separates itself from recipal_list_recipes by emphasizing 'one recipe in full', though no sibling is named outright.

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?

Usage is only implied — an agent infers this is the tool for pulling a single recipe's full detail rather than a list. There is no explicit when-to-use, when-not-to-use, or pointer to recipal_list_recipes / recipal_get_recipe_ingredient as alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by explaining that units_and_grams lists the usable units with their gram weights — useful shape information absent from the schema — but says nothing else about the response payload.

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?

A single front-loaded sentence plus the endpoint path — no filler. It is arguably too terse for a tool with no output schema, but nothing written is wasted.

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 read-only two-parameter getter this is close to sufficient, and annotations cover safety. However, with no output schema, the description only hints at one returned field (units_and_grams) and leaves the rest of the ingredient-line payload undisclosed.

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 id types and constraints, so the schema carries the load. The description adds no extra meaning about the ids beyond echoing them in the URL template.

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 resource precisely (one recipe ingredient line) and adds the GET path, making it unmistakable that this is a single-item fetch. The singular 'one ingredient line' implicitly contrasts with the plural list sibling, though it never names it.

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?

There is no explicit when-to-use statement, no prerequisite (e.g., needing recipe_id from recipal_get_recipe), and no reference to alternatives such as recipal_list_recipe_ingredients or recipal_get_ingredient. The agent must infer usage entirely from the name and path.

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

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

Annotations already declare the read-only, non-destructive, open-world nature, so the description adds useful behavioral context by stating that only currently active costs are returned and that there is one entry per ingredient. It also lists the returned fields, which is valuable because no output schema 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 a single front-loaded sentence that states the scope and returned fields, followed by the endpoint. Every element earns its place, with no redundant restatement of the title.

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 simple paginated read tool with full schema coverage and annotations covering safety, the description is mostly complete because it states the active-cost scope and the returned fields. It could be stronger by clarifying how this differs from the sibling list_ingredient_costs tool, but nothing essential for 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 description coverage is 100% for both page and per_page, so the schema already carries parameter semantics. The description adds no additional parameter detail, which is acceptable but not enriching.

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 clearly identifies the resource as the currently active cost of every ingredient and specifies one entry per ingredient, along with the returned fields. It is understandable without opening the schema, but it does not explicitly differentiate itself from the sibling recipal_list_ingredient_costs, which may return historical or all costs.

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 phrase 'currently active' implies when this tool is useful, but there is no explicit guidance on when to use it versus recipal_list_ingredient_costs or recipal_get_ingredient_cost. No alternatives, prerequisites, or exclusions are named.

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

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

Annotations already establish read-only, non-destructive, open-world behavior. The description adds meaningful context beyond that: it discloses the prerequisite inventory plan and enumerates the returned row fields, which helps an agent understand what data comes back. It does not discuss pagination or rate limits, but the schema covers pagination parameters.

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 compact and front-loads the returned row shape before the prerequisite and endpoint. Every element earns its place, though the 'GET /finished_goods' endpoint is marginally redundant.

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?

With no output schema, the enumerated return fields are valuable and make the tool's output shape understandable. The prerequisite and pagination via the schema round it out; the main remaining gap is sibling disambiguation, which is a usage concern rather than a completeness defect.

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 100%, so all seven parameters, including the three enum parameters, are already documented. The description does not add syntax or meaning beyond the schema, so the baseline of 3 is appropriate.

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 states a specific verb and resource ('Finished-goods stock rows') and enumerates what each row contains (recipe, quantity on hand, unit, packages, lot-code settings, sizes, value). It is clear enough to distinguish this listing operation from a single-record fetch like recipal_get_finished_good, though it does not explicitly name sibling alternatives.

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 only usage guidance is the prerequisite 'Needs an inventory plan.' There is no explicit statement of when to use this tool versus recipal_get_finished_good, recipal_get_inventory, or recipal_list_inventories, nor any when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: what is returned, how it is sorted, and that an inventory plan is required.

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?

Three short sentences cover purpose, downstream use, prerequisite, and endpoint with no wasted text. The return shape and ordering are front-loaded.

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?

There is no output schema, but the description states what comes back (tags with counts, sorted). It also mentions the inventory plan requirement and the endpoint. It could more fully explain the inventory plan context, but it is otherwise complete for a zero-parameter read tool.

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 tool has zero parameters, so the baseline is 4. The schema has no fields to explain, and the description does not need to compensate for any parameter documentation gap.

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 a specific resource (recipe tags), states the return content (tags in use with per-tag recipe counts), and specifies ordering (most used first). This clearly distinguishes it from siblings such as recipal_list_inventory_tags and recipal_list_finished_goods.

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 explicitly says to use the result to filter recipal_list_finished_goods and notes the inventory plan prerequisite. It does not explicitly contrast with recipal_list_inventory_tags, but the resource and downstream use are clear enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: entries are historical, each carries effective date/quantity/unit/price/shipping, and the 'active' entry is defined by the latest effective_at not in the future — semantics an agent could not derive from the schema or annotations.

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?

Two dense sentences with the resource and return shape front-loaded, and no filler. The trailing 'GET /ingredients/{id}/ingredient_costs' is redundant for an agent that already has the tool name and schema, which keeps it from a 5.

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?

There is no output schema, so the description carries the burden of describing return values — and it does, listing the per-entry fields and explaining how the active entry is determined. Combined with a fully documented input schema and read-only annotations, an agent has everything needed to call and interpret this tool.

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 100%: page, per_page and ingredient_id are all documented in the schema itself, including the default and the next_page guidance. The description adds no parameter-level detail beyond that, so the baseline 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 resource and scope — the cost *history* of one ingredient — and enumerates what each entry contains (effective date, quantity, unit, price, shipping). The word 'history' plus the rule for identifying the active entry implicitly separates it from recipal_list_current_ingredient_costs and recipal_get_ingredient_cost, but no sibling is named outright.

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 parenthetical about the latest non-future effective_at entry implies this is the tool for full/dated cost history rather than just the current cost, which is a useful usage signal. However, it never says explicitly when to choose this over recipal_list_current_ingredient_costs or recipal_get_ingredient_cost, leaving the routing to inference.

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

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

Annotations already cover the read-only/non-destructive profile, and the description adds value beyond them: it discloses the returned fields (allergens, units, headline nutrition per 100 g), flags that full=true is large, and states archived records are excluded by default. That default-hiding behavior is the kind of thing an agent needs to know and is not in the annotations.

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?

Three short, front-loaded sentences with zero filler; the return contents come first and the two non-obvious parameter behaviors follow. Nothing is redundant enough to cut.

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?

With no output schema, the description does the necessary work of summarizing the return shape (allergens, units, nutrition per 100 g) and the effect of full=true. Only minor gaps remain, such as not stating the envelope/pagination reply shape, which the schema partially implies via next_page.

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 100%, so the schema already documents all six parameters including the archived enum and pagination. The description only restates two of them (full, archived) with no added syntax or defaults beyond the schema, so the baseline 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 verb and resource ('List your own ingredients (custom and subrecipe ingredients)') and even scopes what 'own' means, which implicitly separates it from recipe-ingredient tools. It does not name a sibling to route against, so a 4 rather than a 5.

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?

Gives useful in-tool guidance ('Set full=true for every nutrient', 'Archived ones are hidden unless asked for'), but never says when to choose this over recipal_get_ingredient or recipal_list_recipe_ingredients. Usage is implied by scope only.

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

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

Annotations already establish that this is a read-only, non-destructive, open-world GET operation. The description adds meaningful behavioral context beyond annotations: the required inventory plan and 403 failure mode, the default sort order, and the set of fields returned. It omits some secondary behavior such as pagination mechanics, but the schema covers those parameters.

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 compact and front-loads the core purpose and returned fields, followed by the prerequisite and default sort. The long field enumeration is useful but slightly dense; the endpoint reference is minor but 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?

There is no output schema, so listing the main returned fields is important and the description does that. Combined with fully documented parameters and read-only annotations, the definition gives an agent enough to call the tool correctly, though it could say a bit more about response envelope/pagination behavior.

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 100%, so all eight parameters are already documented in the input schema. The description adds only the default sort behavior ('weeks remaining, lowest first'), which is largely redundant with the schema's sort_field and sort_direction descriptions; the baseline of 3 is appropriate.

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 clearly identifies the resource as raw-material/ingredient inventory stock rows and lists the key returned fields, so an agent knows what this tool returns. It does not explicitly distinguish itself from nearby siblings such as recipal_get_inventory, recipal_list_ingredients, or recipal_list_inventory_tags, which keeps it below a 5.

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 gives a useful precondition ('Needs an inventory plan, otherwise 403 INVENTORY_PLAN_REQUIRED') and the default sort behavior, which implies it is the list/browse tool for inventory. However, it does not state when to use this versus recipal_get_inventory or recipal_list_inventory_tags, nor when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond them: the result is ordered by usage frequency, each entry carries a count, a prerequisite exists, and the underlying endpoint is disclosed.

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?

Three short sentences: what it returns, what to do with it, what it requires. Front-loaded with the payoff and no filler.

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?

With no output schema and no params, the description carries the return-shape burden and does so (tag + count, sorted). The one soft spot is 'Needs an inventory plan' with zero parameters — it is unclear how that plan is supplied, which could stall an agent.

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?

Zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. No wasted words on nonexistent inputs.

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 verb+resource with its exact payload: ingredient tags in use, each with the count of ingredients carrying it, sorted most-used first. That also implicitly separates it from the sibling recipal_list_finished_good_tags, which serves a different tag namespace.

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?

Explicitly routes the agent forward: 'Use them to filter recipal_list_inventories', and names the prerequisite ('Needs an inventory plan'). It does not state when *not* to call it or what to do if no plan exists, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the full field composition of each returned line (important since there is no output schema) and naming the underlying endpoint. It omits error behavior for unknown recipe ids and ordering, which keeps it from 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?

Two sentences: the payload description is front-loaded, the follow-up hint comes second, and the raw endpoint is appended last. Every clause carries information; nothing is repeated from the title or schema.

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?

With no output schema, the description compensates by enumerating returned fields, and with one read-only param the invocation surface is fully covered. Only the failure mode for a nonexistent recipe_id is left unstated.

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 100% and the single recipe_id parameter is already documented as 'ReciPal recipe id' with bounds. The description only implies the parameter through 'of one recipe'. With high coverage and one trivial required param, the baseline 3 is appropriate.

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 resource (one recipe's ingredient lines) and enumerates exactly what each line contains: ingredient id, name, quantity, unit, waste %, total grams, label display name. This clearly separates it from recipal_get_recipe_ingredient (single line) and recipal_get_recipe (recipe header).

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?

'Use the line ids with recipal_update_recipe_ingredient' gives concrete follow-up guidance, telling the agent this listing is the lookup step before an update. It does not explicitly exclude alternatives like recipal_get_recipe_ingredient, but the read-then-update flow is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful operational behavior beyond annotations: default last-updated sorting, full=true expansion to all nutrients, page-size cap, and last-page detection via fewer than 20 rows.

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 front-loaded with the core purpose and returned fields, then covers sorting, full expansion, pagination, and the endpoint without wasted prose. Each sentence contributes operational information an agent can use.

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 paginated list tool with a fully described schema and read-only annotations, the description supplies a clear return-field summary plus sorting, full-expansion, and pagination termination behavior. Although there is no output schema, the description gives enough context about what comes back.

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 100%, so all six parameters are already documented in the schema. The description mostly restates the schema's full=true, default sorting, and page-size behavior, adding only the useful last-page rule; it adds little for archived, sort_direction, or sort_field.

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 states a specific verb and resource ('List your recipes (products)') and immediately characterizes the returned data, including yield, servings, costs, and headline nutrition. This clearly distinguishes it from single-recipe retrieval siblings such as recipal_get_recipe and from mutation 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?

It establishes the listing use case and explains key options like full=true and pagination behavior. It does not explicitly contrast this with recipal_get_recipe for fetching one recipe, nor does it explain when to use archived filtering, so routing guidance is clear but not complete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description earns credit for going further with consequences annotations cannot express — irreversibility, recalculation of the recipe's nutrition, label and cost, and the fact that only the line (not the ingredient) is removed. It omits failure modes (invalid/historical ids) and whether an updated recipe payload is returned.

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?

Front-loads the WRITE (destructive) tag, then three short sentences each carrying a distinct fact (irreversibility, side effects, recovery path), ending with the underlying route. No sentence is redundant.

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 two-param mutation with no output schema and full annotation coverage, this is essentially self-sufficient: it discloses what is destroyed, what survives, what downstream data changes, and how to undo by re-adding. Only minor gaps remain — response shape and error behavior on a stale or already-removed line id.

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 100% and both required params are documented there, including the pointer that recipe_ingredient_id comes from recipal_list_recipe_ingredients. The description adds no format, range, or sourcing detail 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 verb and resource ('permanently remove one ingredient line from a recipe') and draws two sharp boundaries siblings don't: the ingredient itself is not deleted, and the line can be restored via recipal_add_recipe_ingredient. An agent can distinguish this from recipal_update_recipe_ingredient or recipal_create_ingredient without opening any schema.

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?

Gives clear context for use (removing a whole line, with the explicit recovery path via recipal_add_recipe_ingredient) and clarifies the common confusion that it deletes the ingredient master record. It stops short of an explicit exclusion such as 'use recipal_update_recipe_ingredient to change quantity instead of removing the line', so routing is clear but not fully disambiguated.

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

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

The description adds substantial behavior beyond annotations: the original recipe is not changed, costs and tags carry over, per-serving nutrition stays the same, and scaling down cannot take packages below 1. It also explains default naming, which helps the agent predict the created resource.

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 compact and front-loaded with 'WRITE', then covers scaling semantics, preservation rules, and naming defaults in a single dense paragraph. Every sentence contributes useful selection or invocation context.

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 write tool with rich annotations and full schema coverage, the description covers the key creation, scaling, and preservation behavior. It does not describe the response shape, but no output schema exists and the remaining gap is minor.

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 100%, so the schema already documents all parameters. The description still adds meaningful semantics for scale_amount, including '1 = plain copy' and package-floor behavior, plus the default naming rule for name.

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: 'create a NEW recipe as a copy of an existing one', with scaling behavior clearly stated. It distinguishes this from ordinary recipe creation by emphasizing copying and multiplying quantities/yield.

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 clearly explains the scaling use case, including '1 = plain copy' and the behavior when scaling down. It does not explicitly name sibling alternatives such as recipal_create_recipe, but the context is strong enough for correct selection.

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

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

Annotations only mark this as non-read-only, non-destructive and non-idempotent; the description adds the substantive traits — it is always asynchronous, returns a token rather than a file, the download URL is temporary, and there is a concurrency limit. That is real context an agent cannot get from the structured fields.

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?

Opens with the operation class ('WRITE (render job)'), then the action, then the required follow-up workflow, then the constraint. Every sentence carries distinct information with no repetition of the schema.

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?

There is no output schema, and the description compensates fully by describing what comes back (status plus a token) and how to turn that into the user-visible result (poll, then present the temporary URL). The concurrency limit rounds out what an agent needs to invoke this 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 coverage is 100% and the descriptions for zoom (PNG only) and page_size (PDF only) already explain format-specific applicability, so the schema does the heavy lifting. The description adds marginal value by binding 'PDF or PNG' to the format parameter and exposing the underlying async=true endpoint convention, but adds nothing on recipe_id or the ranges.

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 verb and resource ('start rendering a recipe's nutrition label as a PDF or PNG') plus the return shape ('render status with a token'). This clearly separates it from recipal_get_label (retrieval) and recipal_get_label_render_status (polling) among the siblings.

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?

Gives an explicit workflow: call this, then always poll recipal_get_label_render_status with the token, then hand the user the temporary download URL. It also names the parallel-render cap (5 per account), so the agent knows the operational constraint before calling.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds behavior the annotations cannot express: omitted fields are preserved, nutrients are rescaled when nutrition_unit/quantity change, "measures" is a full replace rather than a merge, and edits propagate into every recipe using the ingredient. The propagation warning is exactly the kind of downstream-destruction disclosure a mutation tool needs.

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?

Six short clauses, each carrying a distinct non-obvious rule, with the write semantics and ownership constraint front-loaded. No restatement of the title and no filler.

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 11-parameter destructive mutation with nested allergens/nutrients and no output schema, the description covers partial-update semantics, replacement vs merge, cascade effects, and archive toggling. Remaining gaps are failure/validation behavior and whether a change can be rolled back after it propagates to recipes — minor, but not nothing for a destructiveHint tool.

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 100%, so a baseline of 3 applies, but the description earns extra credit by explaining the interaction effects the schema cannot: which fields trigger automatic nutrient rescaling, and that measures is replacement-not-merge. It does not touch allergens semantics ("{}" clears all) or nutrient units, but those are already documented in the schema.

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?

Opens with an explicit verb class ("WRITE: change fields") applied to a specific resource ("one of YOUR ingredients"), and immediately scopes it away from public ingredients that cannot be edited. That scope constraint alone lets an agent distinguish it from recipal_create_ingredient or recipal_get_ingredient without inspecting schemas.

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?

Gives a clear condition for use (editing your own ingredient) and a hard exclusion (public ingredients cannot be edited). It does not name a sibling or alternative path — e.g. that reading should go through recipal_get_ingredient or that bulk nutrient edits elsewhere have different tools — so it stops short of explicit routing.

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

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

Beyond annotations (destructive, idempotent, open-world), the description discloses important behavior: omitted fields remain unchanged, dependent recipe costs are affected, subrecipe ingredients are excluded, and it is a PUT to /ingredient_costs/{id}. This adds useful context about side effects and restrictions, though auth/rate-limit details are not covered.

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 front-loaded with 'WRITE', compactly lists the affected fields, and packs side effects, exclusion, and endpoint into a few dense lines. Every clause adds operational meaning without 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 destructive mutation tool with annotations covering safety traits and 100% schema coverage, the description supplies the missing operational context: partial update, cascading recipe-cost impact, subrecipe exclusion, and HTTP method/path. Nothing an agent needs to call it correctly appears absent.

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 100%, so baseline is 3; the description adds value by clarifying that any omitted fields stay unchanged, which is partial-update semantics not stated in the schema. It also maps 'date' to the effective_at parameter and lists the mutable fields in plain language.

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 states a specific verb and resource: 'change an existing ingredient cost entry', lists the mutable fields, and notes partial-update behavior. It distinguishes itself from creation by emphasizing 'existing', but does not name the sibling create_ingredient_cost or get_ingredient_cost explicitly.

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 usage context ('change an existing ingredient cost entry') and one explicit exclusion ('Not allowed for subrecipe ingredients'). However, it does not name alternative tools such as create_ingredient_cost or list_ingredient_costs, so an agent must infer when to choose this over siblings.

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

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

Annotations already declare readOnly=false, destructive=true and idempotent=true, and the description adds genuinely useful context beyond them: omitted fields are preserved, the call recalculates labels and costs, 'default' values trigger derived rebuilds, and the total-weight yield ignores moisture loss. It does not explain the failure mode when recipe_id is unknown or what a partial failure looks like.

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?

A single dense but front-loaded block: operation type first, then mutation semantics, then the two sentinel behaviors, then the exclusion and endpoint. No filler sentences.

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 18-parameter mutation with no output schema, the description covers the semantics an agent most needs: partial-update behavior, sentinel values, downstream recalculation, and the tag limitation. It leaves out error/validation behavior and permission requirements, a modest 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?

Schema coverage is 100%, so baseline is 3, and the description earns an increment by clarifying the two polymorphic parameters beyond the schema: the 'default' sentinel for package_yield_quantity (total ingredient weight, no moisture loss) and for ingredient_list (rebuilt in descending weight order). The remaining 16 parameters are left entirely to the schema.

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?

Opens with an explicit 'WRITE: change fields of one recipe' verb+resource statement and adds the partial-update scope ('fields you leave out stay unchanged'), which separates it from create_recipe and from the ingredient-level update tools. The 'Tags cannot be set here' line further bounds the resource.

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?

Clear about when to use it: partial updates of a single recipe, with the restriction that tags are out of scope. It stops short of naming the sibling to use for tags or stating prerequisites (recipe must exist, permissions), so it is not fully explicit about alternatives.

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

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

Annotations already declare write/destructive/idempotent, so the description's real contribution is downstream consequence: the recipe's nutrition, label and cost change. That tells the agent the blast radius beyond the single line. It does not say whether omitted fields are cleared or preserved on a PUT, which is the remaining behavioral unknown.

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?

Three dense clauses: mutation marker and scope first, the hard limitation second, side effects third, endpoint last. No filler and the constraint that matters is front-loaded.

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 6-parameter mutation with no output schema, the definition covers scope, restrictions, precedence and side effects. The one gap is update semantics for omitted fields, which matters given the PUT-style naming and idempotentHint.

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 100%, so every parameter including the total_grams override is already documented. The description restates the field list and precedence rather than adding syntax, defaults or interaction rules the schema lacks. Baseline 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?

Names a specific verb and resource ('change the AMOUNT of one ingredient line in a recipe') and lists the exact mutable fields. It also states what the tool is not ('It cannot swap the ingredient'), which separates it from recipal_add_recipe_ingredient and recipal_remove_recipe_ingredient without opening either schema.

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?

Gives an explicit when-not with a redirect: to swap an ingredient, remove the line and add another. It also supplies the selection rule between parameters ('total_grams overrides unit and quantity'). It stops short of routing against other near siblings such as recipal_scale_recipe or recipal_update_recipe, which an agent must still disambiguate on its own.

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