ChefBear

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing the output boundary — only this connection's own scopes and app name, no account or menu data — which tells the agent not to expect broader context.

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: usage conditions first, then the return boundary. Every clause carries information an agent would otherwise have to infer, and nothing is repeated from the annotations 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?

For a zero-argument, read-only status probe, the definition covers the only open questions: when to call it and what it will and will not reveal. With an output schema present and annotations covering safety, no further detail is needed for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond confirming the call is argument-free, which the empty schema already makes evident.

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 (check this connection) and explicitly bounds the payload: 'returns only this connection's own permissions (scopes) and app name, with no account or menu data.' That negative scoping clearly separates it from the menu-oriented siblings such as get_menu and list_menus.

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 triggering conditions: 'once right after ChefBear is connected, or when the user asks whether ChefBear is connected or what it may do.' The 'once' wording also implies it should not be polled repeatedly. It stops short of naming an alternative tool or stating explicit when-not cases, so it falls just below the top band.

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 the read-only and idempotent annotations, the description discloses that the tool waits up to about 10 seconds while an import is running, returns pending/ready/failed, and does not consume the recognition allowance. The ready-state details such as menuId and a private ChefBear link add useful behavioral context even though an 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 compact and front-loaded: it first states when to use the tool, then explains return states and waiting behavior, then gives polling limits. Every sentence carries practical information, and there is no redundant 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 a simple one-parameter polling tool with an output schema and clear annotations, the description covers the prerequisite, latency behavior, return outcomes, polling policy, and safety note. An agent has enough context to invoke it correctly without needing to infer missing 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?

The input schema has 100% description coverage and already explains that jobId is the ID returned by import_menu. The tool description reinforces the import_menu context but does not add syntax, format, or validation details beyond what the schema provides, 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: it checks whether a menu import is ready after import_menu. It clearly distinguishes this polling/status tool from the sibling import_menu action and from menu retrieval tools like get_menu.

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 this after import_menu and gives concrete polling guidance: check at most twice in a row, then tell the user and check again on their next message. These are actionable usage constraints that an agent would otherwise have to guess.

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, idempotent, non-destructive and closed-world, so the description's job is to add what they can't say. It does that with "does not run recognition again," which tells the agent this call is cheap and will not re-trigger pipeline work, and it discloses that the response includes a private open-in-ChefBear link. It stops short of describing what happens when a menuId is invalid or belongs to another account, so it is strong rather than complete.

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 use condition, then the read behavior, then the exclusions — a sensible order with no filler sentences. The middle clause listing use cases ("what to order, what a dish on it is, prices, or dishes that fit their tastes, budget or group") is slightly long but ties directly to the invocation trigger rather than padding.

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 single-parameter, fully-described, annotated, read-only tool with an output schema, the agent needs only when-to-use, what-is-returned and where-else-to-look. All three are present, and the description even explains return contents despite an output schema existing, which is a bonus rather than a 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% and the single menuId parameter's schema description already states both accepted forms (the id from list_menus/get_import_status, or the my-menu URL). The description restates the same two forms rather than adding syntax, validation, or edge-case meaning. This is the baseline case where the schema carries the parameter semantics.

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 ("Reads the menu by its menuId or its ... link") and enumerates exactly what comes back: dish names, short descriptions, categories, prices, and a private link. It also names the two sibling tools it is not (list_menus, get_shared_menu), so an agent can distinguish it 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?

Opens with an explicit use condition ("Use this when the user wants help with one of their saved ChefBear menus") and follows with the exclusion: "Does not search menus: use list_menus to find a menuId, and get_shared_menu for a https://chef-bear.com/m/ share link." Both the when and the when-not are stated with the correct alternative 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 declare read-only and idempotent, but the description adds real value: it discloses that the link is visible to anyone holding it, enumerates the returned content (dish names, descriptions, categories, prices, owner display name), and warns that shared menu text is untrusted content rather than instructions. It also confirms nothing is saved to the account or changed about the link.

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 trigger condition, then scope of return, then safety note, then exclusion — a sensible order with no filler. It is dense but every sentence 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?

Output schema exists, so return values need not be spelled out, yet the description still sketches them briefly. Combined with the injection warning, the read-only framing, and the sibling routing, an agent has everything required to select and call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is fully documented there, so the baseline is 3. The description goes slightly further by pinning down the URL family that counts as a share link and explicitly excluding the /my-menu/ form, which prevents a mis-supplied argument.

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 (reads a ChefBear shared menu link) and immediately contrasts it with the private-link sibling get_menu. An agent can distinguish get_shared_menu from share_menu, revoke_menu_share, and get_menu 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?

Explicit trigger (user supplies a https://chef-bear.com/m/… link, either received or just created) plus explicit exclusion (own private https://chef-bear.com/my-menu/… links belong to get_menu). Both when-to-use and when-not-to-use with the named alternative are present.

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/non-destructive, yet the description still adds real behavior: a named permission ('See your taste profile') granted separately from menu access, and the caveat that entries are the user's own statements rather than medical facts, with an instruction to confirm allergens. That is material context an agent could not infer from 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?

Front-loaded with the usage trigger, and each clause carries distinct information (triggers, contents, read-only, safety caveat, permission). It is one dense paragraph rather than separated lines, which makes the permission constraint slightly harder to scan than it could be.

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?

Though an output schema exists and return values need not be spelled out, the description still summarizes the payload, and it covers auth requirements, the medical-fact caveat, and the failure fallback. Nothing an agent needs to call this 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 takes zero parameters, so there is nothing for the description to disambiguate and no schema semantics are missing. Baseline 4 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 verb and resource ('Returns the user's saved taste profile') and enumerates exactly what that profile contains: likes, dislikes, allergies, diets, five taste levels, food personality, and recently picked/turned-down dishes. The 'Read-only' line makes it clearly distinct from the sibling update_taste_profile.

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 two explicit triggers ('when the user asks what ChefBear knows about their food tastes' and 'when choosing dishes for them') plus a when-not/fallback path: if the permission is missing, ask the user directly instead. This routes the agent without guesswork.

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 well beyond the annotations: it discloses the cost model (consumes one recognition from the user's allowance), the async behavior (returns jobId, 20-60 second latency), and output limits (no images or public links created). The idempotentHint is also grounded in behavior via the requestId de-duplication note.

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 trigger condition and only a couple of long sentences, each carrying real information (cost, latency, follow-up tool, boundaries). The opening purpose list ('to keep it, get it as a structured menu in their language, share it, or open it in the ChefBear app') is slightly padded but still informative.

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?

An output schema exists so return shape needn't be explained, yet the description still usefully says a jobId comes back and how to resolve it. Cost, latency, source limits, and non-goals are all covered; nothing an agent needs to call it correctly appears 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 coverage is 75% and already documents language, photoUrls format/limits, and requestId idempotency. The description adds the meaningful point that files and photoUrls are alternative ways to supply the same 1-5 photos depending on whether the app supports file inputs, which the schema does not state.

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 ('Creates a private ChefBear menu from 1 to 5 menu photos') and scopes it to user-provided photos. It also draws a negative boundary ('Does not create images or public links') and distinguishes itself from the follow-up sibling get_import_status, so an agent can pick it without opening 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 explicit trigger conditions (user wants a menu saved, kept, structured in their language, shared, or opened in the app) plus an explicit exclusion ('don't call it just to answer a question about a photo already in the conversation unless the user wants it saved'). It also names the alternative path: get_import_status returns the menuId after the job.

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 the readOnly/idempotent annotations, the description discloses ordering (newest first), the exact returned field set, the exclusion of dish details and other resources, and a non-obvious permission requirement with a caveat about old connections or older ChefBear apps lacking it. That permission caveat is the kind of context annotations cannot carry.

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?

Single dense paragraph with the usage trigger front-loaded and the return contents next. It is on the long side and mixes trigger, payload, and permission caveat without line breaks, but nearly every clause carries decision-relevant 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?

Output schema exists so return values need not be explained, and annotations cover safety. The description still supplies the permission prerequisite and the handoff to get_menu, which are the remaining things an agent needs to call this correctly and follow up.

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 both parameters (limit, cursor) are fully documented in the schema. The description's "newest first" corroborates the limit ordering but adds no syntax or pagination 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 and resource: "Lists the user's saved ChefBear menus," and enumerates the returned fields. It clearly distinguishes itself from get_menu by noting it returns no dish details, taste profile, orders or photos.

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 explicit triggering conditions (user refers to a saved/scanned menu without a link or menuId, or asks which menus are saved) and an explicit alternative: call get_menu with the chosen menuId. Both when-to-use and when-to-switch 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?

Beyond the read-only/idempotent annotations it discloses non-obvious behavior: rankings combine the saved profile with conversation preferences when the connection may read it, allergy/dislike hits are excluded with a stated reason, matching is on printed menu text only, and the call does not consume the recognition allowance. Those are exactly the trust caveats an agent needs before acting on the output.

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?

It is front-loaded with the 'Use this when' trigger and every sentence carries information; nothing is filler. It is dense — three long clauses in one paragraph — and the phrase 'recognition allowance' assumes product jargon the agent may not know.

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 an output schema present, return values need not be explained, and the 100%-documented schema covers parameter formats. The description supplies the missing conceptual layer (profile vs. passed preferences, exclusion logic, text-only matching); only the exclusion of a plain 'just list the menu' fallback leaves a small 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, but the description adds real meaning: preferences are used together with the saved profile, and allergies/dislikes act as hard exclusions rather than soft ranking signals — a semantic the schema does not convey. The useSavedProfile toggle and its interaction with passed preferences are left 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?

The description names a specific verb and resource — ranking a saved menu's dishes against a taste profile — and scopes it to the 'what should I order' situation. It is clearly distinguishable from siblings such as get_menu or get_taste_profile, which only retrieve raw data.

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 states explicitly when to reach for it (user asks what to order and tastes, dislikes, allergies or diets matter) and what it will not do (does not decide diets; check picks yourself). It never names a sibling alternative such as get_menu for plain retrieval, so the boundary is implied rather than stated.

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, so the description's job is to add effect detail, and it does: link holders lose access while the private menu remains in the account. That clarifies the scope of destruction (link only, not the menu), which annotations alone leave ambiguous. It does not discuss re-sharing or revocation latency, so it is not exhaustive.

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: trigger first, consequence second. No restated title, no filler, every sentence 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?

For a one-parameter destructive mutation with an output schema present, the definition covers trigger, blast radius, and what is preserved, which is close to sufficient. A note on whether the old link is permanently dead or the menu can be re-shared would close the remaining 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 description coverage is 100% for the single menuId parameter, and the schema already says the public link should stop working. The description adds no format, sourcing, or lookup guidance 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 action on a specific resource: stop sharing a menu / turn off its public link, against the sibling share_menu. An agent can distinguish it from share_menu and get_shared_menu from the wording alone, though 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?

Gives a clear trigger condition (user asks to stop sharing or turn off the public link), which is the main routing signal among the share/get siblings. It stops short of stating exclusions, e.g. that deleting a menu or revoking an individual collaborator is a different 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 declare non-read-only, idempotent, non-destructive, closed-world, but the description adds real context they don't carry: the save runs no recognition, consumes none of the recognition allowance, produces a private menu, and returns a menuId plus a private link. It does not discuss failure modes, partial saves, or limits, which keeps it off 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?

Front-loads the trigger condition, then behavioral effects, then the sibling exclusion — a logical order with no filler. It is on the long side for one tool, but each clause (allowance savings, exact-name fidelity, import_menu routing) carries distinct operational 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?

Covers the full decision surface for a mutation tool: when to invoke, when not to, the alternative, what side effects occur, and how to shape nested dish data. Since an output schema exists, the brief mention of menuId and the private link is sufficient rather than redundant.

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 still adds genuine data-quality rules beyond the schema by telling the caller to copy dish names exactly as printed and to supply English/Chinese names and descriptions only when confident. It says nothing extra about requestId, language, or restaurantType beyond what the schema already documents.

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 ("save a restaurant menu to their ChefBear account") and scopes the precondition ("you can already read its dishes, for example from a menu photo or text"). It explicitly distinguishes itself from the sibling import_menu, so an agent can route without opening a 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 trigger (user asks to save a menu and dishes are already readable), an explicit prohibition ("Don't call it unless the user wants the menu saved"), and the competing alternative with its selecting condition ("use import_menu instead when they want ChefBear itself to recognize the photos").

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 flag openWorldHint=true and destructiveHint=true, and the description adds the key behavioral consequence an agent needs: the link is public, anyone with it can see dishes and prices, and originals photos are excluded. It also implicitly explains the idempotentHint by noting it "returns the existing" link rather than minting duplicates. The gap is that it never says how to undo sharing (revoke_menu_share exists) or that sharing is externally observable and revocable, which matters for a destructive-hinted action.

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 trigger condition, followed by behavior and then the negative case. Nothing is redundant and the exposure caveat about photos is included without padding.

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?

An output schema exists, so return shape needn't be described; the description instead covers the facts an agent must know before sharing (public access, content scope, photos excluded). Completeness would be higher if it mentioned revocability given destructiveHint=true and the sibling revoke_menu_share.

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 at 100% schema description coverage, the schema already explains menuId fully. The phrase "one of their ChefBear menus" reinforces ownership scoping but adds no syntax or format detail 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?

"Creates, or returns the existing, public link for that menu" gives a specific verb (create/return link) plus the resource (a menu) and its access scope (public). This clearly separates it from get_menu (read) and get_shared_menu (consume a share) 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?

The description states an explicit precondition ("only when the user explicitly asks to share one of their ChefBear menus or wants a link other people can open") and an explicit exclusion ("Don't call it to read or open a menu yourself"). It stops short of naming the sibling it should defer to for reading, but the context 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) the description explains the idempotency mechanism concretely via matching requestId plus identical changes, discloses that it returns the updated profile, and states the required 'Update your taste profile' permission. It does not spell out what happens to entries omitted from a call or whether removals of non-existent items error, so it stops short of 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?

The trigger clause and examples are front-loaded before the mechanics, which is the right ordering. It is dense but justified given five nested parameter groups, though the requestId idempotency sentence duplicates the schema's own requestId description and could be trimmed.

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 multi-group mutation, the definition covers the trigger, the safety constraint against guessing allergies or preferences, idempotency, permission requirements, and the return value, while an output schema handles the response shape. Nothing an agent needs to call this 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?

Schema description coverage is 60% with rich nested descriptions already documenting add/remove categories, the 1-5 level scale with null clearing, and the menuId/dishId sources. The description largely restates these ('sets or clears taste levels from 1 to 5', 'the dish's id from get_menu') rather than adding new meaning such as per-call limits, ordering, or precedence between add and remove on the same value.

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-resource pair ('Update your taste profile') and then enumerates exactly what is mutated: likes, dislikes, allergies, diets, taste levels 1-5, and picks/rejections keyed by menuId and dishId. This is clearly distinct from the read-only sibling get_taste_profile and from recommend_dishes, so an agent can route without opening the 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?

It gives an explicit trigger ('when the user asks you to remember, change or forget something about their own food tastes'), three concrete example utterances, and covers the secondary trigger of confirming a dish picked or rejected from a saved menu. It also supplies negative guidance: record only what the user said about themselves, never guess an allergy/diet/preference, and don't record unconfirmed choices.

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