ifood-mcp

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

Despite annotations already indicating a non-read-only, destructive write operation, the description adds real behavioral context: '401 JSON no-jwt' describes auth failure behavior, 'Item subpaths 404' hints at error behavior, and 'Dual-gated' discloses a gating requirement. 'Does not checkout' clarifies scope beyond 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?

The description is very short and every fragment carries some information, but it is telegraphic and jargon-heavy ('cw-marketplace', '401 JSON no-jwt', 'Dual-gated'). It is not well structured for an agent to parse cleanly.

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, low parameter coverage, and ambiguous overlap with siblings like ifood_create_cart and ifood_checkout, the description is not complete enough. It leaves the agent unsure about return values, exact invocation semantics, and the meaning of the dual-gating requirement.

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 20%, and the description does not explain items, merchant_id, address_id, or response_format. It adds no parameter-level meaning beyond the schema's structure, and the only useful param context comes from explicit_user_intent's schema description rather than the tool description.

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 title and name clearly say 'add to cart', and the description's 'POST /v1/carts' plus 'Does not checkout' gives a rough sense of the operation. However, the description itself is cryptic and never plainly states 'adds items to the cart'; it relies on the title and tool name for meaning.

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

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

The description gives almost no guidance on when to use this tool versus siblings like ifood_create_cart or ifood_checkout. 'Does not checkout' is a useful negative signal, but there is no explicit statement of when this tool is appropriate or which alternative should be chosen instead.

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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds one useful behavioral boundary beyond annotations — 'Does not apply a coupon' — which prevents misuse. However, it does not disclose output behavior, privacy_mode effects, or what data is returned, so the added context is modest.

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 with zero filler; the read-only constraint and coupon exclusion are front-loaded. It is efficiently concise, though slightly terse to the point of omitting a main verb describing the action.

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 tool with two optional enum parameters and no output schema, the description is minimally adequate: annotations cover safety, and the exclusion clarifies scope. Still, it lacks any hint about what the tool returns or how the parameters alter behavior, leaving an agent to guess at the tool's actual output.

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

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

Schema description coverage is 0%, so the description should compensate for the parameters, but it mentions neither privacy_mode nor response_format. The enum values are partially self-explanatory ('summary'/'structured'/'raw' and 'markdown'/'json'), yet the meaning of privacy_mode in particular is left entirely to inference.

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 identifies the resource ('Wallet benefits and coupons') and adds two clarifying constraints: it is read-only and does not apply a coupon. This is more than a tautology and differentiates it from any coupon-application behavior, though it lacks an explicit verb like 'list' or 'view' stating exactly what the tool does.

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: an agent can infer this tool is for viewing wallet benefits and coupons. The explicit 'Does not apply a coupon' provides a when-not condition, but no alternative sibling is named and no positive trigger condition is stated, so routing guidance is limited.

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, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond those flags: this is an 'unofficial' MCP and writes are 'gated,' which helps an agent calibrate expectations. It does not contradict 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?

The description is a single dense sentence with no filler, and it front-loads the read-versus-write scope. It is appropriately brief for a simple introspection tool, though it borders on being too terse to cover usage or return details.

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-required-parameter capability tool, the annotations and description cover safety and the broad purpose. However, there is no output schema, and the description does not explain what the returned capability report will contain, how detailed it will be, or when exactly to invoke 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?

The sole parameter, response_format, is defined in the schema with an enum and default, but the description adds no parameter-level information. With 0% schema description coverage, the description should have compensated, and it does not.

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 as a capability overview for the unofficial MCP, distinguishing readable operations from gated writes. It implies a list/report action and is distinct from the operation-specific sibling tools, though it lacks an explicit verb such as 'list' or 'return'.

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 tool versus the sibling tools, such as 'use this first to discover what actions are available.' The phrasing weakly implies it is a discovery/pre-flight tool, but that inference is left entirely to the agent.

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 annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, and the description merely repeats 'Read-only' without adding operational caveats like return pagination, rate limits, or effect of optional parameters. It surfaces no meaningful behavioral trait beyond what the annotations supply.

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 extremely short and front-loads the key idea. The only minor waste is 'Read-only,' which is already carried by the annotations, but the overall compactness helps an agent parse the tool quickly.

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 read-only category lookup with strong annotations, the description is nearly enough: it states the resource and the spatial scope, and the schema covers the inputs. However, with no output schema and no description of what the returned categories look like or how optional modes affect output, an agent is left with small but real unknowns.

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

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

Schema description coverage is 0%, so the description has to compensate, but it only hints at latitude/longitude through 'near a point.' It does not explain privacy_mode or response_format, and the required coordinate semantics are left to the agent to infer.

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 resource — top-level categories — and scopes it to a geographic point, making the operation reasonably clear despite no explicit verb like 'list' or 'get.' It does not explicitly differentiate from siblings such as ifood_filter_options or ifood_home, so it stops short of 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?

The phrase 'near a point' conveys the intended use case: retrieve top-level categories for a location. However, the description gives no explicit guidance on when to prefer this over sibling tools, no exclusions, and no mention of prerequisites such as authentication or a created session.

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, readOnly=false, and idempotent=false, and the description adds meaningful risk context by stating that the tool 'charges money' and is 'FAIL-CLOSED.' It could further describe irreversibility or refund behavior, but the combination of annotations and description gives the agent a clear safety picture.

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

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

The description is three short, high-signal sentences: risk posture, money-impact, and required prerequisites. It is front-loaded with 'FAIL-CLOSED' and contains no filler or repetition of schema details.

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 non-idempotent, money-charging checkout tool with a nested payload and no output schema, the description is minimally viable but incomplete. It covers the critical safety dimension well, but it does not explain how to build checkout_payload, what response_format affects, or what a successful checkout returns. The sibling tool flow implies this is the terminal payment step, which provides some context.

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 low at 25%, with only explicit_user_intent having a description. The tool description mostly repeats that requirement and does not explain cart_id, response_format, or especially checkout_payload, which is a nested object with no structure defined. An agent would struggle to construct a correct checkout request from the current description.

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 concrete action: 'Charges money on wsloja checkout,' which clearly identifies this as the order-placing/payment step. This distinguishes it from the many read-only sibling tools such as ifood_get_order and ifood_list_orders. The mention of 'wsloja' is somewhat cryptic, so it stops short of 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?

The description gives clear invocation guardrails: 'Requires IFOOD_ALLOW_MUTATIONS and explicit_user_intent,' and the opening 'FAIL-CLOSED' tells the agent to avoid calling it by default. It does not explicitly compare against related mutation siblings like ifood_set_payment_method or ifood_set_delivery_method, but the safety context is strong enough to guide 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, idempotentHint, and destructiveHint false, and the description does not contradict them. It adds minor context by noting token presence and that mutations are off by default, but it remains vague about actual runtime behavior.

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

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

The description is very short and front-loaded, with no wasted words. However, the telegraphic fragments like 'Local doctor' and 'unofficial consumer surface' are jargon-heavy and sacrifice clarity for brevity.

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 status check, the call shape is simple, but there is no output schema and the description never explicitly explains what the response contains. The token/mutation clues help, but the description is not fully actionable on its own.

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 sole parameter, response_format, has a 0% schema description coverage and is not mentioned in the tool description. While the enum and default make it reasonably self-explanatory, the description provides no compensation for the missing schema documentation.

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 labels the tool a 'Local doctor' and mentions 'token present,' which suggests a connection/token diagnostic, but it never directly states what the tool does, e.g., 'returns current connection status.' The cryptic phrasing does not clearly distinguish it from siblings like ifood_capabilities or ifood_privacy_audit.

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?

No guidance is given about when to use this tool instead of a sibling or how the result should influence subsequent calls. 'Local doctor' implies a health check, but no alternatives or exclusion conditions 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 cover read-only, idempotent, and non-destructive behavior, so the description adds value with 'Redacted by default,' which is a meaningful behavioral trait not captured in 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 short sentences, no filler, and the core resource is stated first with the key behavioral note second. Every word earns its place for a tool this simple.

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 tool with optional enum parameters and no output schema, the description states the essential return content and redaction behavior. It is minimally viable, but parameter semantics and usage context are not fully covered.

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

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

Schema description coverage is 0%, and the description does not explain privacy_mode or response_format. The 'Redacted by default' phrase hints at privacy behavior, but it does not tell the agent what each enum value means or how they affect output.

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 concrete resource being exposed: verified emails and phones. It is not a tautology because it adds data-type detail beyond the title, though it lacks an explicit verb like 'returns' or 'lists'.

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

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

The description gives no indication of when to use this tool versus any alternative. Sibling tools exist, but no exclusions, conditions, or alternative recommendations are provided.

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 some behavioral detail beyond the annotations: the endpoint path, a 401 JSON no-JWT auth failure mode, and the fact that PUT/DELETE by :id return 404. It does not describe success behavior, response shape, or the side effects implied by destructiveHint=true, and the required explicit_user_intent is already documented in the schema. The mention of 'create' is not a direct contradiction of destructiveHint, though that annotation is surprising for a creation endpoint.

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 short and front-loads the endpoint, with no filler. However, it is a set of cryptic fragments ('401 JSON no-jwt', 'PUT/DELETE :id 404') rather than clear structured prose, and repeating explicit_user_intent wastes one of its few clauses without adding new 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?

For a 9-parameter mutation with no output schema, low schema coverage, and destructiveHint=true, this description is not complete enough. It leaves out what the required coordinates mean, what a successful creation returns, and what effects or errors beyond 401/404 an agent should expect. The explicit-consent rule is helpful but insufficient.

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 11%, so the description should compensate by explaining latitude/longitude or the other address fields, but it does not. The only parameter-related statement repeats the explicit_user_intent schema description and adds no new meaning. Latitude and longitude are required yet entirely unexplained.

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 identifies a specific HTTP POST to /v1/customers/me/addresses, which clearly signals creating an address for the authenticated customer. Combined with the title, it distinguishes this write operation from read-only siblings like ifood_list_addresses. It is not phrased as a plain verb sentence, which keeps 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?

The description explicitly states that explicit_user_intent is required before calling, which is a meaningful usage condition for a consent-sensitive write. However, it gives no guidance about when to prefer this over alternatives or when not to call it, and it does not explain the relationship to ifood_list_addresses.

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 mark destructiveHint/readOnly, so the bar is lower. The description adds meaningful context: the operation is gated by a feature flag and a user-intent boolean, and it does not finalize a purchase. No contradiction with 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 sentences, front-loaded with the most important gating constraint; every sentence adds information (what, preconditions, boundary) 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?

For a mutation with no output schema and an opaque items parameter, the description is incomplete. It covers safety and gating well but leaves the agent without enough detail on how to build items or which other parameters are relevant, so it is not fully callable from the description alone.

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 only 20%; the description mentions explicit_user_intent but says nothing about merchant_id, items, address_id, or response_format. The items parameter is particularly opaque, and the description does not compensate for the sparse schema, making correct parameter construction under-specified.

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?

Description states a 'gated write' on cw-marketplace with the title specifying cart creation, and explicitly says 'Does not checkout,' distinguishing it from ifood_checkout/ifood_get_cart. The verb and resource are clear enough for an agent to separate this from sibling 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 names concrete prerequisites (IFOOD_ALLOW_MUTATIONS and explicit_user_intent) and excludes checkout behavior. It does not explicitly route to ifood_checkout as the alternative, but it gives clear when-to-use conditions and one when-not.

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 convey read-only, idempotent, and non-destructive behavior. The description adds the non-obvious default behavior that identity is redacted, which is valuable beyond the annotations. It does not contradict 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?

The description is exceptionally concise, with two short sentences that both add meaningful information. The core purpose is front-loaded and there is 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 parameter documentation, the description leaves significant gaps. An agent cannot determine what summary, structured, or raw modes return or how response_format affects the output, despite the annotations covering safety.

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

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

Schema description coverage is 0% and the description does not explain privacy_mode or response_format. 'Identity redacted by default' hints at privacy-related behavior but does not clarify the enum values or what each mode returns.

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 that the tool returns the authenticated customer's profile, making the resource and scope clear. It is distinguishable from sibling tools like order, payment, and merchant tools, though it lacks an explicit verb such as 'get' or 'retrieve'.

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 use this tool versus the many sibling tools. The phrase 'authenticated customer profile' implies the use case, but no conditions, alternatives, or exclusions are provided.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the catalog is public and requires no auth ('200 without auth'), which complements the open-world annotation. It does not disclose behaviors such as pagination, rate limits, or output size, but given the annotation coverage this is acceptable.

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 one short sentence plus a read-only tag, with no filler or repetition beyond the annotation. It front-loads the essential 'Public filter catalog' information before the behavioral note. It earns a top score for economical structure.

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-parameter, optional-parameter tool with rich annotations, the description covers accessibility and read-only nature, but it does not describe what the returned filter catalog contains or how privacy_mode/response_format alter it. With no output schema, an agent has little grounding for interpreting results beyond enum names. The definition is adequate for tool selection but somewhat thin 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?

Schema description coverage is 0%, and the description says nothing about privacy_mode or response_format; it leaves agents to infer meaning from the enum names (summary/structured/raw and markdown/json). The enums are somewhat self-explanatory, but the description does not compensate for the lack of parameter documentation, nor does it explain how these modes affect the catalog output. This is a meaningful 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 identifies the resource as a 'Public filter catalog' and marks it read-only, which tells an agent this tool exposes available search filters. It lacks an explicit verb like 'retrieves' or 'lists', and doesn't distinguish itself from sibling tools such as ifood_categories or ifood_search, but the resource is specific enough to be recognizable.

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 statement 'Public filter catalog (200 without auth)' conveys that the tool is freely accessible without authentication, implying it should be used when an agent needs to inspect available filters. It does not explicitly say when to choose this over alternatives like ifood_search or ifood_categories, nor does it mention any exclusion conditions. This is adequate context but relies on 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description's 'Read-only' merely repeats that. It adds no additional behavioral context such as what happens for missing carts, authentication needs, or response behavior.

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

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

The description is very short and front-loaded, which is good for quick comprehension. The 'Read-only' fragment is somewhat redundant with the annotations, so it does not fully earn its place, but overall the definition is appropriately sized.

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, no parameter descriptions, and no guidance on privacy_mode or response_format, this definition is incomplete for an agent trying to call the tool correctly. The read-only safety profile is covered by annotations, but invocation-specific semantics are 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 0%, so the description needed to explain parameters, but it does not mention cart_id, privacy_mode, or response_format. The property names and enums give minimal clues, but the agent is left guessing what each privacy_mode value means and how response_format affects output.

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 ('Inspect') and a specific resource ('a cart on cw-marketplace'), which clearly identifies the operation. The read-only framing distinguishes it from sibling mutation tools like ifood_create_cart, ifood_set_delivery_method, and ifood_checkout.

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 read-only indication implies this tool is for inspecting a cart rather than modifying or creating one, but no explicit alternatives or when-not-to-use guidance is provided. The usage context is clear but left mostly 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 convey read-only, idempotent, and non-destructive behavior. The description adds only the v3 version marker and the scope constraint 'one order by id'. It does not clarify privacy_mode behaviors or response formatting, but the core safety profile is covered by 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 very concise and front-loaded, with the core purpose in the first phrase. However, 'Read-only' duplicates the readOnlyHint annotation, which is redundant within the description, though it remains efficiently structured.

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 three parameters, no output schema, and no parameter-level documentation, the description is incomplete. It omits guidance on privacy_mode semantics and does not contrast itself with ifood_list_orders, so an agent would need to infer important invocation details.

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

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

Schema description coverage is 0% and the description does not explain privacy_mode or response_format. Only 'by id' hints at order_id. An agent gets no guidance on choosing between summary, structured, or raw, or when to prefer markdown over json.

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 it retrieves one order by ID and notes the API version (v3). This distinguishes it from the sibling tool ifood_list_orders, which handles multiple orders. The read-only nature is also highlighted.

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 'One order by id' implies the tool should be used when a single order is needed and an order_id is available. However, it does not explicitly name alternatives or state when not to use it, leaving the decision 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 read-only/idempotent safety. The description adds useful behavioral context: the dedicated /eta URL returns 404, so the tool reads the live order payload instead. This goes beyond the structured hints and helps set expectations.

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 very short and contains no filler. Each fragment earns its place, though the first fragment is cryptic. It is appropriately sized but would benefit from a clearer statement of what the tool actually returns.

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 read-only tool with strong annotations, the description is minimally viable. However, it lacks any explanation of parameters, output, or how this differs from closely related order tools, leaving an agent to infer some important context.

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

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

Schema description coverage is 0%, so the description should compensate, but it mentions no parameters at all. Parameter names and enums are somewhat self-explanatory, but privacy_mode's summary/structured/raw values and response_format's behavior are left unexplained.

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 clear action: it reads the live order payload for ETA purposes, and the title confirms the resource (order ETA). It is not a tautology and hints at being distinct from order-detail or tracking tools, though it does not explicitly name a sibling.

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?

No guidance is given about when to use this tool instead of siblings like ifood_track_order or ifood_get_order. The description implies read-only usage but does not state conditions, exclusions, or 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, idempotentHint, openWorldHint, and destructiveHint false, so the safety profile is covered. The description adds some context by revealing that dedicated invoice endpoints are broken and that this tool reads the live order payload, but it doesn't disclose return format, pagination, or any other behavioral nuance.

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 short and has no fluff, but it errs toward under-specification. The phrase 'Read-only' repeats what the annotations already state, and the first sentence about 404 URLs is cryptic rather than clarifying. Every sentence has a point, but the overall terseness reduces usefulness.

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 three parameters, no schema descriptions, no output schema, and a large sibling list, the description is too thin. An agent cannot determine what the tool actually returns, how the parameters control the result, or how this tool differs from ifood_get_order and ifood_get_order_receipt. The description answers neither the 'why' nor the 'how' of 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?

Schema description coverage is 0%, and the description provides no meaning for order_id, privacy_mode, or response_format. It does not mention how to extract the invoice from the order payload or how the privacy and format parameters affect the result, leaving the agent without any grounding for correct parameter use.

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 has a verb ('Reads') and a resource ('live order payload'), but it never explicitly says it returns an invoice, which is the tool's declared purpose from its name and title. It reads like a workaround note rather than a clear function statement, and it doesn't distinguish this tool from ifood_get_order, which likely also reads the live order payload.

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 line 'Dedicated /invoice /nfe URLs 404' hints that this tool exists because the direct invoice endpoints fail, but it gives no explicit guidance on when to use this tool versus alternatives like ifood_get_order or ifood_get_order_receipt. No when-to-use or when-not-to-use instructions are provided.

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 annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond that by disclosing the /receipt URL is broken and that data comes from the live order payload, which implies the result may reflect current state rather than a stored receipt.

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 extremely concise, with every segment earning its place: the 404 context explains the need for the workaround, 'reads the live order payload' states the function, and 'read-only' reinforces safety. It is front-loaded and contains 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 the lack of an output schema and 0% schema description coverage, the description is thin on details about what the receipt payload contains or how privacy_mode and response_format alter the result. Annotations and enum names provide some safety and parameter clues, but an agent still lacks enough context to fully anticipate output variations.

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

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

Schema description coverage is 0%, and the description does not explain any parameter beyond implying order_id through the payload context. The enum values for privacy_mode and response_format are self-describing to some degree, but the description does not clarify their behavioral impact, leaving the agent to infer their meaning from the schema alone.

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 the tool's function: it reads the live order payload to obtain a receipt, with the context that a dedicated /receipt URL 404s. The verb 'reads' and the resource 'live order payload' are specific, and the title clarifies this is about order receipts. This distinguishes it from related order tools like ifood_get_order and ifood_get_order_invoice.

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 implies usage by explaining that the dedicated /receipt URL is unavailable, so this tool reads the live order payload instead. However, it does not explicitly state when to use this tool versus alternatives like ifood_get_order_invoice or ifood_get_order, nor does it mention conditions where it should not be used.

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 a useful behavioral warning beyond annotations: 'May WAF from datacenter IPs.' This tells agents that calls from datacenter IPs might fail and they may need an alternative approach. The 'Read-only' statement is redundant with readOnlyHint, so only the WAF warning earns credit.

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 extremely short and front-loaded, with the core purpose stated first. The 'Read-only' clause is redundant with annotations, but overall the definition is economical and scannable.

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, no parameter descriptions, and a four-parameter schema, the description is too thin to be complete. It does not explain what 'home cards' look like, how privacy_mode affects output, or what to do when the WAF blocks the request.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter semantics. 'Localized' hints that latitude/longitude drive the content, but privacy_mode and response_format are completely unexplained, and their enums are not described.

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 identifies the resource (home feed/cards) and the key differentiator (localized), which separates it from siblings like ifood_search or ifood_categories. It is slightly informal and lacks a verb like 'get' or 'list', but the meaning is not ambiguous.

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?

No guidance is given about when to use this tool versus alternatives. It does not mention sibling tools, prerequisites, or scenarios where another tool would be more appropriate.

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, so the description repeating 'Read-only' adds little. However, 'Identity redacted' is a useful behavioral disclosure beyond the annotations, indicating that output is intentionally masked.

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 short and front-loaded with the most identifying information: the exact endpoint. Each phrase carries some weight, though 'Read-only' partially duplicates what annotations already state. Overall it is appropriately concise and well-structured.

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?

The tool has two optional parameters that are completely unexplained, and there is no output schema. While the tool is a simple read operation, an agent cannot determine what privacy_mode settings do or what response shapes to expect. The description is too sparse for fully informed 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?

Schema description coverage is 0%, and there are two parameters (privacy_mode, response_format) with enums. The description does not explain what these parameters mean, how they affect output, or why an agent would choose one value over another. It entirely fails to compensate for the schema's lack of descriptions.

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: 'Allowlisted GET /v1/customers/me/external-identities'. This clearly identifies the exact endpoint and distinguishes it from sibling tools like ifood_customer_me or ifood_contact_methods by resource name.

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 does not explicitly state when to use this tool versus alternatives. 'Allowlisted' and the endpoint provide some context, but there is no guidance on conditions, prerequisites, or why this tool is preferable to related identity/customer tools.

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 read-only, idempotent, and non-destructive behavior. The description adds useful context about the exact endpoint and the 401-without-JWT failure mode, but it does not disclose response structure, pagination behavior, or other runtime traits.

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 containing the endpoint, status filter, and an authentication caveat. There is no filler or redundant information, and every element 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 tool with 4 undocumented optional parameters and no output schema, the description is too sparse. It gives the endpoint and auth behavior but leaves pagination semantics, privacy_mode meaning, response_format behavior, and expected return contents unexplained.

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 4 parameters with 0% description coverage, and the tool description does not mention page, size, privacy_mode, or response_format. The description adds no meaning beyond the schema's bare types and enums, so it fails to compensate for the missing param documentation.

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 a specific verb and resource: listing active iFood orders via a GET endpoint with status=ONGOING. This scope distinguishes it from sibling tools like ifood_list_orders or ifood_get_order, even without naming 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 active/ONGOING framing implies when the tool is appropriate, but there is no explicit when-not guidance or mention of alternatives such as ifood_list_orders for historical orders. An agent must infer usage from the endpoint status rather than being told.

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 annotations already establish read-only, idempotent, and non-destructive behavior, so the description's burden is lower. It adds valuable behavioral context beyond annotations by disclosing that street, phone, and email are redacted by default. This is a meaningful privacy-related behavior that the annotations do not express.

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 extremely concise: two short clauses that immediately state the resource and the key redaction behavior. Every word earns its place, and the most important information 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 simple read-only tool with all optional parameters, the description is minimally viable, especially given rich annotations. However, it does not describe the meaning of privacy_mode values, the response_format options, or any return structure, and there is no output schema. An agent could call the tool with defaults, but it cannot make informed decisions about the available modes.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation, but it does not clearly explain privacy_mode or response_format. The phrase 'redacted by default' hints at privacy_mode, but it never states how 'summary', 'structured', or 'raw' affect output, nor what response_format controls. The enum names are somewhat self-explanatory, but the description adds almost no direct parameter 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 title and description together make the resource clear: saved delivery addresses. The phrase 'Saved delivery addresses' identifies the specific resource and distinguishes it from sibling tools like order, payment, or contact methods. However, the description is a noun phrase rather than a full statement with a verb, relying on the title to convey the 'list' action.

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 no guidance on when to use this tool versus alternatives such as ifood_list_orders, ifood_contact_methods, or ifood_privacy_audit. There are no explicit when-to-use conditions, exclusions, or alternative recommendations, leaving the agent to infer appropriateness from the name alone.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the tool returns past orders using the v4 API, but doesn't disclose pagination behavior, default size, or how privacy_mode/response_format affect 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?

The description is extremely short and free of fluff, but it is under-specified rather than concise: it is a fragment that omits a verb and any parameter context, so its structure doesn't support effective 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?

This is a list operation with four undocumented parameters and no output schema, yet the description only provides a two-word scope. Critical details—pagination defaults, enum semantics, response shape—are absent, leaving the agent without enough to call 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?

Schema description coverage is 0%, and the description says nothing about page, size, privacy_mode, or response_format. The agent must infer meanings from parameter names and enumeration values alone, which is insufficient for correct invocation.

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 title gives the verb+resource ('List iFood orders'), and the description clarifies scope ('Past orders (v4)') and safety ('Read-only'). This distinguishes it from the sibling ifood_get_order, which targets a single order, though it never names that sibling.

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

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

The description gives no guidance on when to use this tool versus the many siblings (e.g., ifood_get_order for a single order, ifood_search for search). The only contextual cue is 'Past orders' and 'Read-only,' which implies safe listing but doesn't state preconditions or 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 and idempotentHint, and the description adds complementary behavioral details: 'Last-four redacted' discloses data sanitization, and 'Does not charge' clarifies there is no external financial side effect. These go beyond the annotations without contradicting them.

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 extremely compact: three short fragments, each adding a distinct piece of information — scope, privacy behavior, and safety. There is no filler or redundancy, and the most identifying detail ('Saved wallet methods') comes first.

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 read-only tool with zero required parameters, the description is mostly adequate: it names the resource, implies the list output through 'Saved wallet methods', and covers side effects and privacy. However, it does not describe the optional privacy_mode or response_format parameters, and since there is no output schema, a bit more guidance about expected output behavior would 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?

Schema description coverage is 0%, and the description provides no help with privacy_mode or response_format. The parameter names and enum values are somewhat self-explanatory, but the description does nothing to clarify how privacy_mode affects the output or how response_format changes the result.

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 identifies the resource clearly as 'Saved wallet methods', which distinguishes it from sibling tools like ifood_merchant_payment_methods. However, the action 'list' is only supplied by the title, not by the description itself, and the phrasing is a noun fragment rather than a specific verb+resource statement.

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?

No explicit guidance is given about when to use this tool versus alternatives. The phrase 'saved wallet methods' implies the user's wallet rather than merchant methods, but it never states this distinction or mentions the nearby ifood_merchant_payment_methods tool, leaving the routing decision 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 flag destructiveHint=true and idempotentHint=true, and the description adds the crucial detail of exactly what gets destroyed: the tokens.json file. It also reinforces the requirement for explicit user intent, which aligns with the destructive annotation. No contradiction exists, and the description provides valuable context beyond the binary hints.

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 short sentences with the core action front-loaded. Every word contributes: the resource being cleared and the critical precondition. There is no filler 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?

Given the tool's simple destructive nature, the description plus annotations provide sufficient context for an agent to call it correctly. It states what will be cleared and what user condition must be met. The lack of return-value information is minor because the tool is idempotent and no output schema exists.

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 only 50% schema description coverage, the description needed to compensate for the undocumented response_format parameter, but it does not. It merely restates the explicit_user_intent condition already described in the schema, adding no new parameter-level meaning.

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: clearing ~/.ifood-mcp/tokens.json. This precisely identifies what the tool does and distinguishes it from all sibling tools, none of which handle logout or token removal.

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 includes 'Requires explicit_user_intent', which is a key invocation condition, but it does not explicitly state when to use the tool or mention alternatives. Since it is the only logout tool in the sibling list, usage is implied rather than directly guided.

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, openWorldHint, idempotentHint, and destructiveHint=false, so 'Read-only' merely repeats readOnlyHint. The description adds no behavioral detail about what data is returned, how privacy_mode affects access, pagination, or any other operational traits.

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 extremely short, but this is under-specification rather than effective conciseness. 'Club / stamps' is unexplained and 'Read-only' duplicates an annotation, so the text does not earn its place with useful 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?

Although the tool has no required parameters and rich safety annotations, there is no explanation of the output content, the meaning of 'club/stamps', or how this tool relates to sibling tools like ifood_benefits. With no output schema and minimal description, an agent has insufficient context to select and invoke it confidently.

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

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

Schema description coverage is 0%, and the description does not mention privacy_mode or response_format at all. The enum values are somewhat self-explanatory, but the description adds no meaning and fails to compensate for the complete lack of parameter documentation.

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 'Club / stamps. Read-only.' conveys a vague subject area and the read-only nature, but it lacks a clear verb and resource phrase such as 'gets loyalty card stamp status'. It does not distinguish this tool from siblings like ifood_benefits or ifood_previous_items.

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 guidance on when to use this tool versus alternatives such as ifood_benefits or ifood_list_orders. The only implied trigger is the loyalty theme, but no explicit context, exclusions, or alternative routing is 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, idempotentHint, and non-destructive behavior. The description adds two genuinely useful behavioral caveats beyond that: the API is unofficial GraphQL (reliability risk) and it may be blocked by WAF from datacenter IPs (an expected failure mode). This is valuable context an agent can act on when the call fails.

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 with zero waste: content summary first, then safety profile, then failure mode. Every sentence earns its place; only 'Read-only' is redundant with the annotations, and it costs a single word.

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 read-only tool, the description covers what data is returned and a known failure mode, while annotations cover safety. Gaps remain: no explanation of what the three privacy_mode values return, no guidance on merchant_id format, and no return-shape description despite the absence of an 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 0%, so the description carries the burden of explaining parameters, yet it mentions none of the three. The enums on privacy_mode (summary/structured/raw) and response_format (markdown/json) are reasonably self-explanatory, and merchant_id is obvious from its name, which prevents a 1, but the description itself adds zero 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?

The description states the resource (iFood merchant info) and the specific data it returns — fees, hours, rating — which makes the tool's purpose clear and distinguishable from the many order/cart/payment siblings. However, the verb is implied ('provides/fetches') rather than explicit, so it doesn't quite earn 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?

The listed data points (fees, hours, rating) imply the trigger condition for using this tool, but the description never states when to use it or names alternatives. With 32 siblings, including the closely named ifood_merchant_payment_methods, explicit routing guidance would materially help an agent choose correctly.

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 repeats 'Read-only', which is already expressed by readOnlyHint=true. It adds no behavioral context beyond the annotations, such as how privacy_mode affects returned data, response formatting behavior, or any operational constraints.

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 very short and front-loaded, with no filler or redundancy beyond the annotation repetition. It is concise, though the brevity comes at the cost of missing substantive guidance.

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 tool with three parameters, including an unexplained privacy_mode enum and no output schema, the description is too sparse. It provides the basic domain concept but fails to address parameter behavior, output structure, or when it should be selected, leaving clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate by explaining the parameters. It does not mention merchant_id, privacy_mode, or response_format at all, leaving the agent to infer meaning solely from names and enums.

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: how a restaurant accepts payment, and 'Read-only' signals the operation type. It is clear enough for an agent to know what data the tool provides, though it does not explicitly distinguish itself from sibling tools like ifood_list_payment_methods.

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?

No guidance is provided about when to use this tool versus alternatives. The description mentions no use cases, prerequisites, or comparison to related tools such as ifood_list_payment_methods or ifood_set_payment_method.

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, openWorldHint, idempotentHint, and destructiveHint=false, so 'Read-only' merely restates structured data. The description adds no behavioral context such as empty-result behavior, merchant-not-found handling, or the data-privacy implications hinted at by the privacy_mode parameter.

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 core resource is stated in a single front-loaded sentence with no waste. The second sentence, 'Read-only,' is redundant with the annotations but remains a harmless one-liner that would still help an agent unable to see annotations.

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 0% schema coverage, no output schema, and two enum parameters that materially change behavior, the description leaves the agent guessing about output shape and parameter effects. The annotations fully cover the safety profile, but the operational picture is incomplete.

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

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

Schema description coverage is 0%, so the description must compensate, but it only contextualizes merchant_id ('at this merchant'). It says nothing about privacy_mode (summary/structured/raw) or response_format (markdown/json), leaving two behavior-shaping parameters entirely undocumented.

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 identifies a specific resource — items ordered before at a given merchant — which differentiates it from siblings like ifood_list_orders (orders, not items) and ifood_get_cart (current cart). However, the retrieval verb is implied rather than stated explicitly ('Items you ordered before'), preventing a top score.

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?

No guidance is given for when to use this tool versus alternatives. With 24 siblings including ifood_list_orders, ifood_get_order, and ifood_search, the description never states a selection condition, leaving the agent to infer applicability from the tool name alone.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a small but meaningful behavioral hint: the tool is concerned with privacy redaction defaults and fail-closed behavior. It does not, however, explain what kind of audit output to expect, whether it scans across orders/merchants, or what 'fail-closed' concretely means for the returned data.

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 extremely short—seven words—so it is concise by volume. But it is closer to a tagline than a specification. It front-loads the core idea, yet omits the verb and resource needed to make those words useful. A good short description can be one sentence, but this one does not fully earn its brevity because it leaves key interpretive work to the 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 tool with no output schema, no parameter documentation, and a cryptic description, an agent has very little to go on. The annotations confirm it is a safe, read-only, idempotent operation, which is useful, but the description does not explain what an audit contains, how to interpret 'redaction defaults' or 'fail-closed checkout,' or how the response_format affects the output. Given the 0% schema description coverage and absent output schema, this is a significant completeness 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 0%, so the description carries the burden. However, with only one parameter (response_format), which is an enum with a default, the parameter is effectively self-documenting: markdown vs json output. The description doesn't mention the parameter, but little is lost because the enum names are self-explanatory and the schema provides the default. The description could have noted how the audit output is structured, but the parameter itself is simple.

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 phrase 'Redaction defaults and fail-closed checkout' suggests an audit-related operation about privacy redaction and checkout security, which is somewhat actionable. However, it lacks a clear verb and resource: it doesn't explicitly say what the tool does (e.g., 'audit', 'list', 'review') or what it operates on, leaving an agent to infer the tool's scope and distinguish it from the many iFood sibling 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?

The description provides no explicit guidance on when to use this tool versus alternatives like ifood_checkout, ifood_get_order, or ifood_connection_status. The term 'fail-closed checkout' implies a relationship to checkout or security/privacy auditing, but the description does not state conditions, prerequisites, or exclusions, so an agent cannot reliably determine when it should be invoked.

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 only behavioral claim, 'Read-only,' merely restates the readOnlyHint annotation and adds nothing beyond it. The description does not explain how privacy_mode affects the returned data, what response_format controls, or whether any filtering or pagination applies, especially with no output schema present.

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 very short, but the 'Read-only' fragment duplicates annotation data, and 'Merchant reviews' is an under-specified noun phrase. This reads as under-specification rather than deliberate, efficient conciseness.

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 a 0%-coverage input schema, the description leaves the agent without enough information to know what review data is returned, how privacy modes differ, or how the response format behaves. It is minimally usable but incomplete for a tool with three configurable parameters.

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

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

Schema description coverage is 0%, so the description must compensate for the three undocumented parameters, but it mentions none of them. merchant_id, privacy_mode, and response_format are left entirely unexplained beyond their literal schema names and enum labels.

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 identifies the resource ('Merchant reviews') and signals that the tool is read-only, but it lacks an explicit verb such as 'get' or 'list'. It is not a tautology, but it does not sharply differentiate itself from review-adjacent sibling tools like ifood_merchant_info.

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 guidance on when to use this tool versus alternatives, and no mention of exclusions, prerequisites, or typical use cases. The noun-phrase description only implies that it is related to merchant reviews.

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 value beyond the annotations by disclosing that datacenter IPs may trigger WAF blocking, which is non-obvious and operationally important. The 'Read-only' phrase reinforces the readOnlyHint, and the WAF caveat provides meaningful behavioral context. It does not contradict 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?

The description is extremely concise at roughly a dozen words, front-loaded with the action, and every phrase adds information. The WAF warning is a single short clause that earns its place, and there is no filler 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?

The annotations cover the safety profile well, and the WAF warning adds a useful operational detail. However, with six parameters, no output schema, and no explicit sibling routing, the description leaves meaningful gaps around parameter behavior and when to use the tool. It is minimally adequate but not complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it only clarifies that `term` is the search query and `latitude`/`longitude` define the point. It leaves `size`, `privacy_mode`, and `response_format` unexplained, and those parameters are not self-evident beyond their enum values. The description provides partial semantic coverage at best.

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 the action ('Search') and resource ('restaurants/items near a point'), giving agents a concrete sense of what the tool does. It does not explicitly differentiate from siblings like ifood_categories or ifood_merchant_info, but the 'near a point' scope is distinctive enough to avoid obvious confusion.

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 'near a point' implies this tool should be used for location-based restaurant or item searches, which is useful context. However, it does not explicitly say when to prefer this over sibling tools such as ifood_categories or ifood_home, nor does it provide any exclusion criteria. Guidance is present but left 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 indicate this is a non-read-only, destructive, non-idempotent operation, so the description does not need to repeat that. It adds the useful 'Gated cart write' framing, but does not disclose what makes the operation destructive or what side effects changing the delivery method may have.

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 extremely concise, front-loads the core 'Gated cart write' concept, and contains no filler words. It is structured well, though it is so terse that it depends heavily on the schema for operational meaning.

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 gated, destructive write operation with four parameters and no output schema, this description is incomplete. It does not explain how the gate is satisfied, what the response looks like, or what happens to the cart when the method changes, so an agent has limited ability to invoke it confidently.

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 25%, and the description does not compensate. The allowed method values are already present as an enum in the schema, and cart_id, response_format, and explicit_user_intent receive no added semantic explanation 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 title plus description make it clear this sets the delivery method on an iFood cart, and the listed DEFAULT / PRIORITY / TAKEOUT values identify the target field. It is distinct in resource from ifood_set_payment_method, but the description does not explicitly differentiate it from that sibling.

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?

No guidance is given for when to use this tool versus related tools like ifood_set_payment_method. 'Gated' implies some precondition, but the condition is not explained, and no explicit when-to-use or when-not-to-use context is 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 establish that this is a read-only=false, destructive write. The description adds meaningful behavioral context beyond annotations: the operation is gated and does not charge, which is important for an AI agent deciding whether this action has financial consequences. This exceeds what the structured annotations alone provide.

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 short, front-loaded sentences with no filler. Every word adds value: 'gated' signals a precondition, 'cart write' identifies the resource and mutation, and 'does not charge' prevents a critical misunderstanding.

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 mutating tool with no output schema, the description explains the core intent and a key non-effect (no charge), and the explicit_user_intent schema property covers gating. But it lacks prerequisites, return behavior, and explicit relationship to sibling tools like checkout or list_payment_methods, leaving some invocation context incomplete.

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 25%; only explicit_user_intent has a schema description. The description does not explain cart_id, payment_method_ids, response_format, or the intent-gating requirement beyond the schema. 'Gated' hints at explicit_user_intent, but most parameter semantics are left undocumented.

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 phrase 'Gated cart write. Does not charge.' clearly identifies the operation as a write to a cart's payment method and explicitly distinguishes it from charging/checkout behavior. The specific resource ('payment method') is only implied by the name and title, but combined with the context this is sufficiently clear.

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 'Gated' wording implies that explicit user intent is required before invoking this write, and 'Does not charge' implies it is intended for cart configuration rather than checkout. However, there is no explicit when-to-use vs. when-not-to-use guidance, and no alternative tools 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context by explaining that dedicated tracking URLs return 404 and that this tool reads a live GET payload, meaning data may change between calls. This goes beyond the annotation information and does not contradict it.

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 extremely compact and front-loads the critical failure mode ('Dedicated /tracking URLs 404') before giving the endpoint and safety note. Every sentence contributes without repetition or 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 should clarify what the agent actually receives when tracking an order, such as status fields or delivery progress. It also leaves privacy_mode and response_format semantics unexplained, so an agent cannot confidently know how to control the output or interpret the result.

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

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

Schema description coverage is 0%, so the description must compensate. It only makes order_id inferable from the endpoint; privacy_mode and response_format are not explained at all, leaving their effects on the tracking output unclear despite having enum definitions.

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 gives a concrete verb and resource: it 'Reads the live GET /v3/customers/me/orders/:id payload' and ties that to order tracking. Mentioning that dedicated /tracking URLs 404 helps distinguish it from a literal tracking endpoint, though it does not explicitly differentiate it from sibling tools like ifood_get_order.

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 workaround context: dedicated tracking URLs are broken, so this tool reads a live payload instead. However, it does not explicitly say when to prefer this over sibling tools such as ifood_get_order or ifood_get_order_eta, leaving the choice somewhat implied.

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