The Pantry Butler

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

Annotations already signal that this is a mutating but non-destructive operation. The description adds useful context about accepting plain-language input and gives examples, but it does not disclose behavior such as duplicate handling, quantity parsing, or what the response will be. This is adequate but not rich.

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 sentences, each earning its place: the action, the input format with examples, and the trigger conditions. It is front-loaded and contains no filler or redundant schema 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?

This is a low-complexity tool with a well-described schema covering both parameters and a default for location. The description provides the action, input style, and usage triggers. It does not explain what happens after items are added, but that is not essential given the simple nature of the tool and no output schema.

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 adds value by reinforcing the 'plain language' expectation with concrete examples like '2 lemons' and 'half a bag of spinach', which help an agent understand the intended format for the items parameter.

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 opens with 'Add items to the kitchen', a specific verb and resource that directly matches the tool's function. It clearly distinguishes this tool from siblings like list_pantry, cook_tonight, and save_recipe, which all have obviously different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit trigger conditions: 'Use this when they mention shopping, unpacking groceries, or having bought something.' It does not mention when not to use it or name alternative tools explicitly, so it stops 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, and the description adds valuable behavioral detail beyond that: it explains the ranking mechanism ('ranked by how much of each they already own'), reveals the output includes named missing ingredients, and defines the meaning of `can_make: true`. It does not contradict 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?

The description is concise and well-structured. It front-loads the core purpose, then provides usage context, and ends with a clarification of a key output field. Every sentence earns its place, with no fluff or redundancy.

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, idempotent tool with a single optional parameter and no output schema, the description is remarkably complete. It covers what the tool does, when to use it, what output to expect, and even defines a potentially ambiguous field (`can_make`). There are no missing critical details that an agent would need to invoke it 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?

The only parameter, `limit`, is 100% covered by the schema, whose description is clear ('How many recipes to return, best matches first.'). The description doesn't add extra semantics for the parameter, but given full schema coverage, a 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 tool's purpose: to return recipes the person can cook with what they already have. It uses a specific verb ('returns') and names the resource ('recipes'), and it distinguishes itself from siblings like list_recipes and add_pantry_items by focusing on 'what is already in their kitchen.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'whenever they ask what to cook, what's for dinner, what they can make without going to the shop, or what to do with what they have.' It also implies when not to use it (e.g., when they want to browse all recipes, they would use list_recipes), and the examples of user queries make the trigger conditions very clear.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context by specifying the content of the listing (pantry, fridge, freezer) and that it includes expiry dates where known. This goes beyond the annotations without contradicting them, though it could also mention the return format more explicitly.

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 two sentences with no fluff. The core purpose is front-loaded, and the usage guidance is appended efficiently. Every word earns its place, making it highly scannable for an agent.

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 listing tool with no parameters and no output schema, the description covers what it does, what it returns (with expiry where known), and when to use it. It is adequate for an agent to invoke correctly, though it could specify whether the output is a flat list or grouped by location, which is a minor 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?

With zero parameters, the description does not need to explain parameter semantics. The schema coverage is effectively 100% (no parameters), and the baseline for 0-param tools is 4. The description correctly focuses on the tool's behavior rather than parameters that don't exist.

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 action (list) and resource (kitchen contents including pantry, fridge, freezer), and clearly distinguishes it from sibling tools like add_pantry_items or list_recipes. It also provides concrete use cases such as 'what they have' and 'what is about to go off', making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool ('Use this when they ask what they have, what is in the fridge, or what is about to go off'), providing clear triggers for invocation. While it does not mention alternatives, the contexts are specific enough to avoid misuse, and the scope is well-defined.

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, idempotent, and non-destructive behaviorcars. The description adds useful behavioral details beyond this: the result order (newest first) and the inclusion of the creator for each recipe, which helps the agent set expectations about the response.

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 with no filler. The first sentence immediately states what the tool returns and key ordering, and the second provides invocation context. Every clause earns its place.

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 parameterless read-only listing tool with strong annotations-checked safety hints and a sibling set for scope context, the description is complete. It covers what is returned, ordering, source attribution, and when to use it. No output schema exists, but the return shape is sufficiently described.

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 per the rubric. The description adds return-value semantics about ordering and creator attribution but does not need to document parameters, since none exist.

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: listing saved recipes, sorted newest first, and including the creator. It clearly differentiates from siblings like add_pantry_items, save_recipe, and list_pantry by focusing on saved recipes rather than pantry items or actions.

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 'Use this when they ask what they have saved or want to find a recipe by name,' giving clear context for when to invoke the tool. It does not name alternative tools or exclusion criteria, but the guidance is unambiguous and sufficient for this simple read-only tool.

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 provide read-only, idempotent, and non-destructive hints. The description adds value by specifying what data is returned (plan, recipe count) and the explicit negative guarantee that an email address is never returned, going beyond the structured 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 sentences with no filler. The core return content is front-loaded, and the exclusion is stated immediately after 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 parameterless, read-only identity tool with no output schema, the description fully covers the return contents and the one important edge case (no email address). Nothing needed to invoke the tool correctly 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?

The tool has zero parameters and schema coverage is 100%, so there is no parameter burden for the description to carry. The baseline of 4 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?

The description clearly states what the tool returns: the connected account, their plan, and saved recipe count, plus an explicit exclusion (never an email address). This distinguishes it from sibling tools like list_recipes and list_pantry, which act on different resources.

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 strongly implies when to use it (to identify the current account and account-level data), but the description does not explicitly state when to use it versus alternatives or provide any exclusion conditions. It relies on the name and obvious purpose rather than direct guidance.

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