Japan Restaurant Calories

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value by disclosing the return shape (counts, nutrients, source, fetch date), but says nothing about result volume, ordering, or pagination for what could be a long list.

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 sentence that front-loads the core purpose and then the returned fields before the parameter note. Nothing is wasted, though it is packed into one sentence rather than cleanly separated.

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, disclosing the returned fields is essential and done well, and the filter behavior is explained. The main omission is scale/pagination context for a list that could be large, but otherwise it is complete enough to invoke 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 0% and the schema only names the parameter, so the description must compensate; it does clarify that 'query' is a chain-name filter rather than a free-text search. However, it omits matching semantics (exact vs substring, case sensitivity), leaving gaps.

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 the restaurant chains covered') and enumerates the returned fields (item counts, nutrients, source document, fetch date). It is clearly distinct from siblings like search_menu and sum_items, though it does not name them 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 clause 'query filters by chain name' gives implied usage of the sole parameter, but there is no explicit when-to-use guidance or routing versus alternatives such as search_menu. Usage must be inferred from the purpose.

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 supply the generic hint set (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false); the description goes well beyond by disclosing exactly what is stored (chain, item, note), that no personal information is kept, that requests are counted but not shown publicly, and that coverage is not guaranteed. That is rich, decision-relevant behavioral context for a write tool.

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 first sentence front-loads the action, and each subsequent sentence adds a distinct rule or caveat without filler. It runs five sentences, which is slightly long for a three-parameter tool, but nothing 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?

With no output schema, the description carries the return-behavior burden and does so: the request is counted, not displayed, and does not guarantee the chain will be added. What is missing is only minor — nothing about failure handling or repeat/spam behavior, though the 'one request per chain or item' rule covers most of that.

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%, with each parameter (chain, item, note) already documented including maxLength and examples. The description only restates which fields are stored, adding no format or constraint 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 action and resource: telling the site operator that a restaurant chain or menu item is missing. The subject matter (missing chain/item) is distinct from the siblings list_chains, search_menu, and sum_items, 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 an explicit precondition — 'Use only after search_menu / list_chains could not find it AND the user actually wanted it' — naming the sibling tools to try first, plus a cardinality rule ('One request per chain or item'). Both when-to-use and when-not are covered.

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?

Goes beyond the readOnly/idempotent annotations by disclosing that zero-result queries are logged anonymously to prioritize chains, and that nutrient filtering only works for chains that publish that nutrient. Sort behavior (relevance with a query, kcal ascending otherwise) is also disclosed. It stops short of pagination or result-cap behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded, opening with purpose before matching rules and sorting. Most sentences carry distinct information, though the single long paragraph packs several unrelated concerns (logging, matching, sorting, output fields) without visual separation.

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 9-parameter, no-output-schema tool with annotations already covering the safety profile, the description covers matching, filtering, sorting and returned fields (id, page url, source_file) adequately. Only minor gaps remain around pagination limits and result-count 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 only 33%, so the description carries real weight: it explains query token semantics (AND on spaces, kana/width normalization, nickname matching across name/size/category/genre/chain), the nutrient constraint, and default sort. It adds little for the self-evident limit/offset/kcal-bound params, keeping it just under the top score.

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 ('Search menu items of Japanese restaurant chains') plus the payoff ('get their nutrition facts'). It also distinguishes itself from siblings by noting the item id is what feeds sum_items, so an agent can route between the two 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 concrete usage context: combine query with chain/genre/kcal range, and use 'nutrient' to find items rich in a nutrient. It does not explicitly state when NOT to use it versus list_chains or request_missing, but the operating guidance is clear enough to act on.

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 non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses that unpublishable nutrients surface in an `incomplete` field and that totals can be underestimates, which is important data-quality context absent from the schema.

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, front-loaded with the action and scope, followed by the one caveat that matters. 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, the description usefully explains the `incomplete` reporting behavior, which is the main thing an agent must interpret from the result. It leaves quantity/limit semantics and any response structure unstated, but for a one-parameter read-only tool this is nearly sufficient.

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 reported at 0% for the single nested `items` parameter, and the description only reinforces the id source (search_menu). It says nothing about the `quantity` multiplier, its 0.1-20 range, or the 30-item cap, so it does not fully compensate for the coverage gap. Baseline 3.

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+resource (add up nutrition for a set of items) and even scopes the use case (a meal, a day). It also points at the sibling search_menu as the source of ids, so the agent can separate it from list_chains and request_missing.

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 when it applies (totaling a meal or a day) and states the prerequisite that ids must come from search_menu. It does not name any alternative or exclusion, but there is no competing summing tool among the siblings, so this is close to complete.

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