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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the required id format, which is genuinely useful behavioral context, but says nothing about what 'full details' contains, error behavior for a stale id, or whether the city component affects results.

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

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

A single sentence with no waste, front-loading the action and immediately following with the one constraint that matters. Nothing is padded or repeated from the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the description covers the critical input format but leaves the return shape and failure modes unstated. It is adequate to make the call but not complete enough to set expectations about the response.

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

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

Schema coverage is 0% and the schema only types id as a string, so the description carries the full burden. It does so by specifying the exact composite format product:<item_id>:<city>, which an agent could not infer from the schema alone. It stops short of explaining what each segment means or whether city is optional.

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 pairs a specific verb (fetch) with a specific resource (full product details) and clarifies the scope as 'full details' versus the summary results from search. It does not, however, distinguish itself from the sibling foran_product_details, which an agent could easily confuse with this tool.

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 implies the usage sequence by saying the id is 'returned by search', which tells the agent this is a follow-up call. It gives no explicit when-not guidance and never names foran_product_details or foran_search_products as alternatives, so the routing decision is only partially supported.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that this is a static facts surface with no side effects, but says nothing about auth requirements, freshness of the facts, or what the response looks like. With annotations carrying the safety burden, this is adequate rather than rich.

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

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

Two sentences, zero waste. The content inventory comes first and the actionable usage instruction follows, which is correctly front-loaded for an agent scanning for a trigger.

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-param, no-output-schema info tool this is close to complete: the agent knows what topics come back and when to reach for it. The only gap is the missing boundary against sibling info tools like foran_policy and foran_buying_guide.

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

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

The tool takes zero parameters, so there is no parameter meaning to add and the baseline of 4 would normally apply. The description instead spends its words on the content topics it returns, which is useful but is coverage rather than parameter semantics, landing it at a solid middle score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource (facts about Foran Delivery) and enumerates the topics covered: live areas, delivery time, hours, cashback, promo, payments, contact, app links. That is far more informative than the title alone. It stops short of explicitly distinguishing itself from overlapping siblings such as foran_policy or foran_find_location, so an agent must infer the boundary.

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

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

It gives an explicit trigger: "Call this first when a user asks what Foran is or where it delivers." That is clear sequencing guidance for a zero-param static-info tool. It does not state when NOT to use it, e.g. that store-level delivery checks belong to foran_find_location.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context about what the tool actually contains — procedural guidance on ordering, fees, payment, top-up, cashback, and refunds — which tells the agent this is static explanatory content rather than live account data. It does not explicitly say the output is non-personalized reference text, which keeps it from a 5.

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

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

Purpose is front-loaded in the opening clause, followed by a topic inventory and a usage sentence; every element earns its place. The topic list is dense and comma-heavy, but for a reference tool that inventory is the most valuable part.

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-parameter read-only reference tool with no output schema and annotations covering safety, the description supplies everything needed to call it correctly. The one remaining gap is routing versus the sibling foran_about and foran_policy tools, which an agent must guess at.

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

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

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline for a no-parameter tool is 4.

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 concrete resource ('Practical guide to buying from Foran Delivery') and enumerates the exact topics it covers (one-store rule, delivery charges, minimum order, payment, Foran Money, cashback, custom orders, cancellation/refunds). That is far more specific than a title restatement. It stops short of a 5 because it never distinguishes itself from overlapping siblings such as foran_about and foran_policy.

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

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

'Use it whenever a customer asks how Foran works or how to order' gives a clear triggering condition. There are no exclusions, so an agent facing a general 'tell me about Foran' question cannot tell whether this or foran_about is the right call.

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, idempotentHint=true and openWorldHint=true, so the risk profile is covered. The description adds real context beyond that: the operation is only valid for pending orders and there is a mandatory human confirmation gate. It does not say what cancellation triggers (refund, notification) or what happens on failure, which keeps it from a 5.

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

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

Two short sentences: the eligibility constraint comes first, the required confirmation workflow second. Every clause carries operational information 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?

For a destructive, no-output-schema mutation with four parameters, the definition supplies the essential preconditions and the confirm workflow an agent needs to call it safely. The remaining gaps — post-cancellation effects, error behavior when status is not pending, and reason semantics — are meaningful but secondary.

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 session_key is documented). The description meaningfully explains when to set confirm=true, which the schema cannot convey via a bare default of false. However, the required 'reason' parameter (3-200 chars) is never addressed, so the description only partially compensates for the coverage 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?

States a specific verb and resource ('Cancel an order') and narrows scope with a precondition ('that the store has not started yet (status pending)'), which is enough to separate it from siblings such as foran_track_order or foran_order_status. It stops short of naming any alternative tool by name, so it lands just below the top mark.

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

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

Gives a clear use condition (order still pending) and a required call protocol: get customer confirmation first, then pass confirm=true. The negative case (what to do when the store has already started the order) is only implied by the status gate rather than stated, so no explicit alternatives are offered.

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 disclose this is a non-readonly, non-idempotent, non-destructive mutation, so the description's added value is the same-store constraint, which is genuine behavioral information not present in schema or annotations. It does not explain the non-idempotent behavior that matters most here – whether adding the same item twice increments quantity or creates a duplicate line – nor any auth or stock/availability failure modes.

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

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

Three short, front-loaded sentences with no filler; the action is stated first, then the constraint, then the conditional options rule. Slightly clipped to the point of omitting needed context, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter mutation with annotations covering the safety profile and no output schema, the description covers the essential constraint and the options prerequisite. The remaining gaps – non-idempotent duplicate behavior and the mart/bites module choice – are meaningful but secondary, so it is close to complete rather than fully 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 coverage is 67%, and the schema already documents module, options, variant and session_key. The description adds only a pointer to foran_product_details for discovering valid option values, while module selection (mart vs bites) and quantity semantics go unexplained beyond the schema's own text. Baseline 3 is appropriate given the moderate coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Add a product to the customer's cart'), which is unambiguous against most siblings such as foran_cart_remove, foran_cart_update and foran_place_order. It does not explicitly say how it differs from foran_cart_update (which presumably changes quantity/existing lines), so it falls short of full sibling differentiation.

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

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

Gives a useful precondition (all items in one order must come from the same store) and routes the agent to foran_product_details when the product has options. It never states when NOT to use it (e.g. to change quantity on an existing line, use foran_cart_update) and does not mention that a logged-in session_key is required, leaving real usage decisions implied.

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 destructiveHint=true and idempotentHint=true, so the safety profile is carried by structured data. The description adds the useful detail that removal can target either a line or the entire cart contents, but it omits precedence when both cart_id and all are supplied, whether the cart persists when emptied, and whether errors are returned for unknown cart_id.

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

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

A single short sentence that front-loads the primary mode (one line) and then the secondary mode (empty cart). No filler, and the parameter names are used inline as anchors.

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 four-parameter destructive mutation with no output schema, the definition covers the two removal modes but not the result (does it return the remaining cart?), the module scoping, or the interaction between cart_id and all. Annotations cover safety, so the remaining gap is behavioral detail rather than risk disclosure.

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 50% schema coverage the description contributes meaning for cart_id and all, but says nothing about module (mart vs bites), which is documented only in the schema, or how it interacts with removal scope. session_key is explained in the schema, so the description does not need to repeat it, but the relationship between cart_id and all remains undefined.

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 (remove) and resource (cart line / whole cart) and enumerates its two modes via the parameter names. It is clear enough to distinguish from foran_cart_view and foran_cart_add, though it never explicitly contrasts itself with foran_cart_update, which can also reduce quantities.

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

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

Usage is implied by the parenthetical parameter hints: pass cart_id to drop a single line, pass all=true to clear everything. There is no explicit guidance on when to prefer this over foran_cart_update (e.g. setting quantity to zero), and no preconditions such as requiring a valid session_key or an existing cart.

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 idempotency, non-read-only status, and non-destructiveness; the description adds the important behavioral fact that quantity 0 deletes the line, which annotations alone would not reveal. It does not state whether the call returns the updated cart or totals, but that is a minor gap given the annotation coverage.

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

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

Two short sentences, zero filler, and the core action is front-loaded ahead of the cart_id source and removal caveat. Every clause carries information the agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple four-parameter mutation with no output schema, the description covers the action, the key input's origin, and the special-case behavior. It leaves out what the response contains and whether a session must be established first, but those are handled by the schema's session_key documentation.

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 50%, with cart_id and quantity undocumented in the schema, so the description must compensate. It does: cart_id's provenance is named and quantity's zero-value semantics are spelled out, covering both gaps (the 0-50 bound remains schema-only but is self-evident).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Set a new quantity for one cart line'), which immediately separates it from generic cart tools. It does not explicitly name foran_cart_remove as the alternative, but the 'quantity 0 removes it' clause effectively disambiguates the overlap.

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

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

It states where cart_id must come from (foran_cart_view) and clarifies the removal case, so an agent knows the main precondition and the edge case. It stops short of saying when to prefer this over foran_cart_remove, which is the one remaining routing ambiguity among siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by saying what comes back (line totals and subtotal), which matters because there is no output schema, and by tying the result to the logged-in customer's session.

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

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

One sentence, front-loaded with the action and resource, with the module scope and return content packed in. No filler or redundant restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, fully described, read-only lookup, the description covers purpose, scope, and return contents. It could mention behavior for an empty cart or an expired session_key, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, with the module enum values already explained ('mart = groceries and daily needs; bites = restaurant food') and session_key tied to foran_login. The description adds nothing about parameters beyond restating the module scope, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Show the customer's current Foran cart') and scopes it to the two modules, Mart or Bites. The read-only 'view' framing separates it from foran_cart_add/update/remove 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 read-only nature implies this is the inspection step before modifying or checking out, but the description never states when to call it versus foran_cart_add, foran_cart_update, or foran_place_order. Usage is inferable from the verb and siblings rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the dual-mode behavior (categories vs. items-in-category), which is genuinely beyond the annotations. However, it is silent on whether a location is required in practice, on the mart/bites module split, and on what 'limit' bounds — meaningful gaps for a live-service browse call.

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

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

A single sentence with the primary behavior front-loaded and the variant mode introduced by 'or, with category_id'. No filler, and the parenthetical examples do real work in showing what a category looks like.

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 six-parameter, no-output-schema tool, the description covers the core listing behavior but omits the module dimension (mart groceries vs. bites restaurant food) and the location requirement, both of which materially change results. An agent could call it correctly in the default case but would be guessing on module and location scoping.

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 67% schema coverage, the description usefully compensates for the one undocumented parameter, category_id, by explaining that supplying it changes the result from a category list to the items within a category. That is real meaning beyond the bare integer type. It does not touch module or limit, which the schema partially covers on its own.

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 specific verb ('List') plus resource ('product categories') and concrete examples (Milk & Dairy, Fruits & Vegetables). It also states the second mode clearly: with category_id it returns 'the items inside one category.' It does not name or contrast with the closest sibling, foran_search_products, which also surfaces products, 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 implicitly tells the agent how to switch modes ('with category_id'), which is useful usage guidance for a single tool with two behaviors. But it never says when to prefer this over foran_search_products, nor does it mention that a city or latitude/longitude is effectively needed to get results — the schema lists all six parameters as optional, so the agent gets no routing signal on location or module.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that results are scoped to the authenticated customer and lists the returned fields, but says nothing about expiry, whether coupons are auto-applied at checkout, or how many are returned. With annotations carrying the safety burden, this is adequate but thin.

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

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

A single tight sentence with the resource front-loaded and the return fields parenthetically clarified. Nothing is redundant, though the brevity comes at the cost of any usage framing.

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 read-only lookup with full schema coverage and annotations present, the definition gives enough to call it correctly and even previews the response shape. Missing only eligibility/expiry nuance and any indication of how the coupons relate to order placement.

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

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

Schema description coverage is 100%, so both session_key and the mart/bites module enum are already documented in the schema. The description contributes only the phrase "logged-in customer," which gestures at session_key without adding format or behavior details beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (coupons) and constrains it to those the logged-in customer can actually redeem, then enumerates the returned fields (code, discount, minimum order). No sibling tool deals with coupons, so an agent can route here without confusion, though it distinguishes itself by absence of competition rather than explicit contrast.

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?

"Can use" implies applicability filtering by the logged-in customer, which hints that this is a pre-checkout eligibility lookup. There is no explicit when-to-use statement, no mention of relation to foran_place_order or foran_cart_view, and no exclusions or prerequisites stated.

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

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

The description adds a lot beyond the annotations: the order lands in the admin panel as a pending 'Claude order' with photos attached, custom prices are confirmed by the team before dispatch, there is an Rs 150 MCP fee, and the first call returns a non-committal quote. However, nothing explains what happens if the order fails after confirmation, whether retrying is safe given the non-idempotent annotations, or the delivery charge rules beyond the latitude note. It adds real context but leaves the failure/retry surface opaque.

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

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

It is front-loaded with the core verb and resource, and each sentence carries a distinct obligation (store rule, outcome, auth modes, confirm flow, payment). The paragraphs are dense run-ons, and some parenthetical detail could be tightened, but almost nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter mutation tool with no output schema, the description covers the critical gaps: what the first call returns (quote with items, delivery charge, fee, total, warnings), how auth modes work, how custom vs catalogue items are built, and that the order is pending admin confirmation rather than finalised. An agent has enough to call it correctly without guessing.

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 81%, so the schema already carries most parameter meaning; the description usefully adds the mode split (session_key for customers vs staff_session + customer_name/phone for staff) and the item construction rule (item_id for catalogue, name + estimated_price_rs for custom). It does not explain the interaction between address and address_id, or what images/confirm do beyond what the schema already states, so it is a moderate increment rather than a full semantic layer.

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 first sentence states a specific verb and resource ('Create a Foran order') plus the input shapes it accepts (product names, shopping list, photos). It explicitly distinguishes itself from the catalogue-only path by explaining that custom items (name + estimated_price_rs) can be mixed with catalogue items (item_id), which is what separates it from foran_place_order and foran_cart_add.

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 the alternative tools to call while preparing the order (foran_list_stores / foran_search_products) and states the selection rule: one store, nearest open, most items. It also gives the mandatory two-step flow (first call without confirm for a quote, then repeat with confirm=true after an explicit yes) and states the payment method (cash on delivery).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the call returns coordinates and a deliverability verdict, which is useful behavioral context given there is no output schema, but it says nothing about no-match handling, ambiguous/multiple matches, or service failures.

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

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

One sentence, front-loaded with the primary action, with the secondary deliverability check and inline examples all earning their place. 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?

For a one-parameter read-only lookup with no output schema, the description conveys input expectations, the two outputs (coordinates, deliverability), and the real-world scope. It is nearly complete, missing only failure/ambiguity behavior, which is a minor gap at this complexity level.

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

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

Schema coverage is 100% and the single parameter is already documented as 'Address, area or landmark', so the baseline would be a 3. The description goes beyond it with two concrete example queries in local naming conventions ('Precinct 10 Bahria Town', 'Qasimabad Hyderabad'), which clarify the expected granularity and format of the query string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('turn an address or area name into coordinates') plus a second function ('check whether Foran delivers there'), which no sibling tool performs. It does not explicitly contrast itself with adjacent tools like foran_list_stores or foran_my_addresses, so it stops short of full sibling differentiation.

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 is a pre-order deliverability/geocoding step — but there is no explicit 'use this when' statement, no exclusions, and no pointer to alternatives such as checking saved addresses via foran_my_addresses. The two examples hint at expected input, but routing guidance is 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 declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful result-shape context (open status, minimum order, distance) that matters for selection, but it omits pagination/limit behavior, default ordering, and what happens when no location is supplied.

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

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

A single well-formed sentence with the key distinguishing information front-loaded and no filler. It is efficient, though arguably undersized for a six-parameter discovery tool with zero required fields.

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 required parameters and no output schema, the description covers the essence but leaves real gaps: no guidance on location resolution (saved address vs. coordinates), defaults (limit 20, filter all), or distance units. Adequate, 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 67%, so the schema already documents city, module, latitude and longitude. The description reinforces the Mart/Bites meaning and the delivery-area scoping but adds nothing about filter (all/popular/latest) or limit, leaving those to bare enum/default values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource precisely — stores (Mart) or restaurants (Bites) that deliver to the customer's area — and lists the decision-relevant attributes returned. It doesn't differentiate itself from siblings like foran_store_details or foran_search_products, and the verb 'list' only appears in the tool name/title, not the description body.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. The description never says to use this instead of foran_search_products when the customer wants to browse rather than search, nor does it reference the location requirement (city OR latitude/longitude) that governs a valid call.

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

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

Annotations declare a non-read-only, idempotent, open-world operation, and the description adds what they cannot: the return value is a session_key that other tool families depend on, plus a security rule about credential provenance. The env-var fallback for local installs is behavior an agent could not infer from the schema or hints. Minor gap: nothing about session expiry or failure modes.

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

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

Three sentences, front-loaded with the capability, then the credential-sourcing rule, then the local-install exception. Each sentence carries distinct information with no restatement of the name or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an auth tool with a small schema and no output schema, the description covers what the agent needs: inputs, their provenance, the downstream session_key, and the no-argument variant. It is slightly incomplete on what a failed login looks like and how long the session_key stays valid, which matters because the whole tool set depends on it.

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

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

Schema coverage is 50% – only phone is documented. The description compensates partly by explaining that password is the same as the Foran app and that both may be omitted on a local install, which explains why required is empty. However it does not describe the phone format itself or validate the schema's example, so it adds meaning rather than fully substituting for the undocumented password field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Log in with the customer's own Foran phone number and password" names a specific verb and resource, and the qualifier "customer's own" implicitly separates it from foran_staff_login. It also states the payoff (a session_key for cart, order and account tools), so the agent knows why to call it. It stops short of explicitly naming the staff-login sibling as the alternative.

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

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

It gives concrete when-to-use conditions: only credentials the customer typed themselves in this conversation, with an env-var path on local installs (call with no arguments). That is real routing guidance plus an exclusion on where credentials may come from. It does not explicitly say when to use foran_staff_login instead, leaving that inference to the sibling names.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. Because there is no output schema, the field list in the description is genuinely useful disclosure of what comes back. But it omits any behavioral detail such as what happens with an expired session_key or whether the balance is live versus cached.

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

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

One short sentence with no filler, and the most distinctive information (wallet balance, loyalty points) is front-loaded. The only flaw is structural: without a leading verb the sentence reads as a data label rather than a tool definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool with no output schema, the field enumeration covers most of what an agent needs. Still missing are the relationship to the overlapping foran_wallet sibling and any failure behavior, both relevant given the crowded sibling set.

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?

There is a single parameter with 100% schema description coverage; the schema already explains that session_key comes from foran_login. The description adds nothing about the parameter, but with full coverage the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description enumerates the profile fields (name, phone, wallet balance, points, order count), which lets an agent infer this reads the logged-in customer's account. However, it is a bare noun phrase with no verb, so the action ('retrieve the current customer's profile') is only implied. It also overlaps ambiguously with the sibling foran_wallet, which presumably returns the wallet balance alone.

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 when-to-use guidance at all — nothing says when to pick this over foran_wallet, foran_my_orders, or foran_my_addresses, all of which return subsets or neighbors of this data. No prerequisites or exclusion conditions are stated.

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

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

With readOnlyHint=true and openWorldHint=false already declared, the description adds genuinely new behavioral context: this is a read-only view of existing data that cannot be mutated through the tool, since address creation happens externally. The remaining gap is the return shape (a list of addresses with ids), which is not described, but the key operational constraint is disclosed.

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

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

Two short sentences with no filler, and the primary purpose comes first with the ordering prerequisite attached directly to it. The second sentence covers the constraint in a single clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the agent has what it needs: what the tool returns conceptually, why to call it, and that creation is out of band. It would be marginally stronger if it hinted that the result is a list keyed by address_id, but nothing critical is missing.

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

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

There is a single parameter, session_key, and schema description coverage is 100%, with the schema itself pointing back to foran_login. The description adds no meaning beyond the schema, which is acceptable at this coverage level but is the baseline rather than added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource precisely ('The customer's saved delivery addresses') and the parenthetical clarifies the practical purpose (address_id is needed to place an order). It doesn't use an explicit retrieval verb, so an agent infers the read behavior from 'saved' plus the title, but the resource and scope are unambiguous and clearly distinct from order, cart, and location siblings.

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

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

It gives a concrete use case (fetch address_id before placing an order) and, importantly, an exclusion: new addresses cannot be added here, they are created in the Foran app or website. That steers the agent away from attempting a create flow, though it doesn't explicitly name a sibling alternative or say when the list might be empty.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds scope context — that a single call covers both running orders and history — but says nothing about authorization (the session_key dependency), pagination behavior, or what fields come back. This matches the calibration case where a scope constraint earns a 3 against solid 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?

A single front-loaded sentence fragment with zero filler; the key distinction (active vs. history) appears immediately. It is efficient, though the fragmentary form omits any verb describing the retrieval 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?

Given three parameters with only one documented, no output schema, and a dense cluster of order-related siblings, the description is too thin to guide confident selection. It never explains how this differs from order details, order status, or tracking, which is the main ambiguity an agent faces here.

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

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

Schema description coverage is only 33%, so the schema documents little beyond session_key. The description's mention of "running" and "past order history" implicitly maps to the `which` enum, but the `limit` parameter (default 10, max 30) is never referenced, and the session_key requirement is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"The customer's running (active) orders or past order history" names a specific resource (the customer's orders) and its two scope modes (active vs. historical), which an agent can distinguish from cart or product tools. It stops short of differentiating itself from close siblings such as foran_order_details, foran_track_order, and foran_order_status.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternatives, even though the sibling list contains at least four other order-related tools. The agent must infer from the name alone whether to call this or foran_order_details / foran_order_status / foran_track_order.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered, but the description adds nothing beyond the annotations. It does not state that access is limited to the customer's own orders, what happens with an invalid or foreign order_id, or whether an expired session_key causes failure.

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

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

One short, front-loaded sentence with no wasted words. It is efficient, though the elliptical fragment style leaves the action implicit rather than stating 'retrieve'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly names the returned content (items, prices, status), which is the most valuable thing it does. It is still thin for a tool in a crowded order-related family, leaving the order_id source and session requirements 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?

Schema coverage is only 50%: session_key is documented as coming from foran_login, but order_id has no description anywhere. The description never mentions either parameter, so it does not compensate for the undocumented order_id (e.g., where the caller obtains it).

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 fragment 'Items, prices and status of one of the customer's orders' identifies the resource and roughly what is returned, so the purpose is inferable. But it is a noun phrase without a verb, and it does nothing to distinguish this from close siblings like foran_order_status, foran_track_order, and foran_my_orders, which all sound like order lookups.

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 versus foran_order_status, foran_track_order, or foran_my_orders, and no mention of prerequisites such as needing an authenticated session or where an order_id comes from. The agent must infer routing 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 and openWorldHint=true, so safety is covered; the description adds genuinely new behavior: customer calls are restricted to the caller's own orders, staff phone lookups return the latest 5 orders only. It stops short of explaining where session_key/staff_session come from (presumably foran_login/foran_staff_login) or what happens when no identifier is supplied.

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

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

Three tight sentences with no filler, each doing a distinct job: payload contents, caller routing, invocation trigger. Arguably the long return-field list is placed ahead of the more decision-relevant caller-routing rule, but the ordering is defensible and nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by enumerating the returned fields, and it explains both access modes and the staff result limit. Remaining gaps are how to obtain the session credentials and behavior when no selector is passed — modest for a read-only status tool with 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 coverage is only 25% — just the phone field is documented — so the description must carry the rest, and it largely does: session_key is identified as the customer credential scoped to own orders, staff_session as the staff credential, and the order_id/phone pair is explained as alternative selectors with a 5-order cap on phone. Only order_id itself is left to inference, which is minor.

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 (a Foran order) and an explicit capability (real-time status) and enumerates exactly what the response carries: stage, timeline, store, rider name/phone, items, delivery charge, total, payment. That is far more concrete than the title alone. It does not, however, distinguish itself from close siblings like foran_track_order or foran_order_details, so an agent still has to guess which of the three answers a status question.

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

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

Gives a clear use trigger ('whenever someone asks where is my order?') and splits the calling convention by caller type: customers pass session_key and are scoped to their own orders, staff pass staff_session plus order_id or phone. What is missing is any exclusion or alternative routing, e.g. when to prefer foran_track_order or foran_my_orders 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?

Beyond the annotations, it discloses the order-summary approval step, payment options, and the MCP fee of Rs 150 that must be shown to the customer. It does not explain post-placement behavior, failure modes, or reversibility, though the annotations already mark this as non-read-only, open-world, and non-idempotent.

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

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

The description is front-loaded with the checkout action and two-step confirmation rule, then adds payment and fee context. Every sentence provides actionable instruction or required customer-facing detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter mutation with no output schema, it covers the critical confirmation flow, payment methods, and fee disclosure. It stops short of explaining what the order summary contains or what the final order response provides, but the schema and annotations fill many of those 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?

The schema already covers 75% of parameters; the description adds procedural meaning for confirm and clarifies payment_method options including wallet as Foran Money. It leaves rider_tip_rs, module, and coupon_code details largely to the schema or 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 states a specific action: checking out the current cart to a saved address. It clearly distinguishes this from sibling cart and order-status tools by focusing on final order placement.

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

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

It gives an explicit two-call flow: first without confirm to obtain a summary, then with confirm=true only after customer approval. It does not name alternative tools, but the when/when-not guidance for confirm is strong and actionable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety and locality profile is settled structurally. The description adds only that this is a read of a fixed set of policy documents – nothing about whether content is store-specific, localized, or free-form text. With annotations carrying the behavioral load, this is adequate but thin.

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

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

A single front-loaded sentence with no filler; the verb and resource lead and the value list follows. It is slightly more of a fragment than a structured statement, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a low-complexity, single-required-enum tool with no output schema, so the definition needn't explain return formatting. What is missing is minor: whether the response is a text blob or structured fields, and how store scoping works, but nothing prevents a correct call.

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%, but the single parameter is an enum whose six allowed values the description reproduces. That repetition confirms the accepted inputs without adding new semantics such as what each policy actually contains; baseline 3 for a one-param tool whose schema enumerates the domain.

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?

"Read a Foran policy" gives a specific verb plus resource, and the enumerated list (terms, privacy, refund, cancellation, delivery, about) makes the tool's scope immediately graspable. It does not, however, distinguish itself from the sibling foran_about or foran_buying_guide, which plausibly cover overlapping content.

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

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

Usage is only implied by the list of retrievable policy types; there is no statement of when to pick this over foran_about (which shares the "about" value) or foran_buying_guide. An agent can infer intent, but the ambiguity with the sibling about tool is left unresolved.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description genuinely adds one behavioral trait beyond that — that the response enumerates required options which must be resolved before ordering — but says nothing about location dependency (city vs. latitude/longitude), module scoping, or what happens when an item is unavailable in the given city.

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

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

A single sentence with zero filler, front-loading what is returned and following with the operational consequence. Nothing is repeated from the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With five parameters, no output schema, and location-dependent behaviour, the definition should say more: where item_id comes from, whether city/module affect availability or pricing, and roughly what the returned detail set contains. As written it covers the essential purpose but leaves real gaps for a location-scoped, open-world read tool.

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

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

Schema description coverage is 80%, so the city, module, latitude and longitude parameters are already well documented in the schema and the enum values are self-explanatory. The description adds no parameter guidance and leaves item_id entirely unexplained — notably it doesn't say the id comes from foran_search_products — so this lands at the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource ('Full details of one product') and adds the payload's key content: required options such as size, flavour, and add-ons. It doesn't explicitly name a sibling, though 'before adding it to the cart' implicitly separates it from foran_cart_add and foran_search_products.

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

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

It gives a clear workflow trigger: call this before adding the item to the cart, which tells the agent this is the pre-add inspection step. It stops short of naming foran_cart_add or stating when not to use it (e.g. for browsing instead use foran_search_products).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only, open-world nature is covered. The description adds real value beyond that by naming the return fields (item_id, price, store, stock, link) and clarifying that prices include discounts, which is useful pricing semantics not stored anywhere else. However, it is silent on the location requirement ('near the customer' only hints), on the fact that results are confined to live cities, and on what happens when no city or coordinates are supplied.

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

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

Two tight sentences with no filler: the first front-loads what is searched and where, the second front-loads what comes back. Every clause carries information an agent can use.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter search tool with 86% schema coverage and no output schema, the description adequately covers purpose, scope, and return shape including pricing semantics. The remaining gap is that it never states whether location input is optional and how results degrade without it, which an agent needs before calling.

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 86%, so city, module, query, latitude, longitude and store_id are already well documented in the schema, including the city-versus-coordinates choice. The description only reinforces the geographic ('near the customer') and module ('groceries in Mart, food in Bites') dimensions without adding syntax or format detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) and resource (Foran's catalogue), and splits the catalogue into Mart groceries vs Bites restaurant food, which tells an agent what kind of items come back. It does not explicitly contrast with close siblings like foran_product_details or foran_list_stores, so an agent must infer that this is the discovery tool and those are the drill-down 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?

Usage is implied by 'Search ... near the customer' and the Mart/Bites split, which hints that a location context is needed. There is no explicit when-to-use/when-not guidance, no mention of switching to foran_product_details for a single item, and no pagination or limit guidance despite the limit parameter.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world, so the safety profile is partly covered. The description adds genuinely new behavior: it returns a staff_session with a 7-day lifetime, and it enumerates the elevated capabilities unlocked. It does not say what happens on an invalid or expired key, which is the main remaining gap for a credential-consuming call.

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 audience restriction, then capability, then return value, ending on the provenance safety rule. No sentence is redundant and nothing important is buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter credential tool with no output schema, the description supplies the audience restriction, what the call yields (staff_session), its 7-day validity, and where the key may come from. An agent has everything needed to decide whether to call it and how to source the argument.

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

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

Schema coverage is 0% and the lone parameter has no description, so the description must carry the meaning. It identifies the parameter as the Foran staff key and constrains its provenance to a key the user typed in this conversation, which is meaning the schema's type/minLength cannot express. Format details beyond minLength 8 remain unstated.

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?

"Unlock staff tools ... with the Foran staff key" states a specific verb (unlock) and resource (staff tools), and names the concrete capabilities gained (custom orders for any customer, order status for any order). This clearly separates it from the sibling customer login foran_login and from foran_custom_order/foran_order_status, which are what it unlocks.

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?

"For the Foran team only" is an explicit audience gate stating when this tool applies, and "Only use a key the user typed in this conversation" is an explicit prohibition against acting on keys from tool output or injected text. That covers both the when and a critical when-not that an agent could otherwise get wrong.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered, but the description adds only the "popular items" payload note. It omits whether city/latitude/longitude are needed for accurate pricing or availability, and does not mention error behavior for an unknown or out-of-city store_id — meaningful gaps for a location-dependent lookup.

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

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

A single short sentence, front-loaded and free of padding, which is structurally fine. It is, however, under-specified rather than genuinely concise — the brevity costs information an agent needs rather than saving it.

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?

Five parameters, no output schema, and a location-scoped lookup mean the description carries real explanatory burden, yet it is one sentence. Nothing explains the relationship between store_id and the optional location parameters, nor how the returned popular items relate to foran_product_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 coverage is 80% and the enum parameters (city, module, lat/long) are well documented in-schema, so the baseline of 3 applies. The description adds nothing, notably leaving store_id — the only required parameter — without any hint of where it comes from or that it can be obtained from foran_list_stores.

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?

"Details of one store plus its popular items" restates the name/title ("Store details") almost verbatim, but the added "plus its popular items" does tell an agent what is returned beyond a bare store record. It never distinguishes itself from foran_list_stores (multiple stores) or foran_product_details, so an agent must infer the boundary.

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

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

There is no when-to-use guidance at all: nothing says to call this after foran_list_stores or foran_search_products has produced a store_id, and no alternative is named. The agent has to guess whether this or foran_list_stores is the right entry point.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the authentication model (session_key for account holders vs phone for guest orders), which is genuinely useful context beyond the annotations, but it says nothing about failure behavior when credentials don't match, rate limits, or what the status payload contains.

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

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

Two short sentences, purpose front-loaded, no filler. The first sentence is arguably too terse to be useful, but nothing is wasteful or buried.

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?

Absent an output schema, the description should convey what a caller gets back; "status of an order" is thin on that. With three params, two auth modes, and several near-duplicate siblings, the definition covers credentials but not the distinguishing context an agent needs to call the right tool 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?

The schema already documents phone and session_key (67% coverage); the description only restates that pairing in slightly different words and adds no syntax, format, or validation detail. The required order_id has no description anywhere, though its meaning is largely self-evident from the name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Status of an order" names the resource and the kind of result, but it is a bare noun phrase that essentially restates the title "Track an order." It does not distinguish this tool from close siblings such as foran_order_status, foran_order_details, and foran_my_orders, so an agent cannot tell which to pick from the description alone.

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 a real conditional rule for invocation: logged-in customers use session_key, guest orders use phone. However, it offers no when-to-use guidance relative to the very similar sibling tools (foran_order_status, foran_order_details), 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 declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, closed-domain read. The description adds the transaction categories, which is modest context, but says nothing about ordering (newest first?), pagination, or empty-wallet behavior. With annotations covering the safety profile, this is adequate but not rich.

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

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

A single short sentence with the key scoping word ("Recent") front-loaded and zero filler. It is efficient but so terse that it reads as a label rather than an instruction, which slightly undercuts the front-loading benefit.

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 read tool with no output schema this is close to sufficient, but it omits the two things an agent most needs: what a returned transaction contains and how the limit parameter affects the result. Simple tool, thin description, borderline acceptable.

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 50%: session_key is documented in the schema as coming from foran_login, but limit has only min/max/default constraints and no meaning anywhere. The description does not explain that the result is capped or how "recent" relates to limit, so it fails to compensate for the coverage 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?

"Recent Foran Money (wallet) transactions" names a specific resource and scope, and the cashback/top-ups/payments list tells an agent what content to expect. It is clearly distinguishable from sibling order tools like foran_my_orders or foran_order_details, though the verb is only implied (a fragment, not "List").

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

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

There is no explicit when-to-use or when-not guidance, and no mention of alternatives such as foran_my_orders for purchases versus this wallet ledger. The word "recent" hints at recency scoping but doesn't say whether older transactions are reachable or how this differs from order history.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context beyond that: the search spans only live areas, and the result shape is ids intended for `fetch`. It still omits result limits, pagination, and what an empty result looks like, so a 3 is appropriate.

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, front-loaded with the action and scope, with the return-value hint second. Every clause carries information; the area parenthetical is slightly incidental but still conveys real scope.

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, no-output-schema, read-only search tool, the description covers purpose, geographic scope, and the follow-up call. It is incomplete on query semantics and on how it differs from the near-identical `foran_search_products` sibling, both of which an agent needs before calling.

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 single `query` parameter is documented nowhere. The description never says what `query` matches (product name, category, store, fuzzy vs exact, language), so it fails to compensate for the schema gap on the only input that matters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Search Foran products") plus the scope ("all live areas (Bahria Town Karachi and Hyderabad)"), which is more than a restatement of the name. However, it does nothing to distinguish itself from the sibling tool `foran_search_products`, which by name appears to do the same thing, so an agent cannot confidently pick between them.

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?

"Returns ids usable with fetch" implies a two-step workflow (search here, then call `fetch` with the ids), which is genuine but implicit usage guidance. There is no explicit when-to-use or when-not-to-use statement and no mention of `foran_search_products` as the alternative, which is the most consequential omission given how similar the two names are.

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