Unfactory

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

Annotations already flag a non-read-only, non-idempotent, non-destructive write, and the description adds real value with the ten-item cap, the consent rule, and the makeable/someday modeling rules. However, it never resolves the most important behavioral ambiguity for a non-idempotent write: whether the call appends to an existing list or replaces it, and what happens on duplicate wishes. That gap matters more than the return format, which needs no explanation given there is no output schema.

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

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

Three dense sentences, each carrying distinct rules, with the cap and resource front-loaded. Some phrasing is domain jargon ('Unfactory', 'lane') that a fresh agent must parse from context, but no sentence 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?

For a mutation with nested wish objects, an enum source, and no output schema, the definition covers most decision-relevant rules and needs no return-value explanation. Completeness is undercut by the unexplained required wish_token and the unstated append-vs-replace semantics, both of which an agent needs before calling 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 description adds substantial meaning to nested fields the flat schema barely covers: it defines the three source values, explains makeable_id vs. its absence, and links lane 'someday' to closest_makeable_id/closest_idea. But wish_token is required and is never mentioned anywhere in the description or in a schema description, and the top-level source is only explained indirectly through examples.

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

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

The description opens with a specific verb and resource: 'Save up to ten wishes to the person's wish list', and clarifies what the list is. It is clearly distinguishable from read-oriented siblings like my_wishes and most_wished, though it never names the closest sibling (make_wish) to draw the boundary 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?

Strong conditional guidance: which source value applies to which situation, when to supply makeable_id versus omit it for unmakeable physical things, when to use lane 'someday' with a closest makeable substitute, and a consent precondition ('Only add what the person has agreed to'). It stops short of naming alternatives such as make_wish or start_three_wishes, so the agent must infer the routing.

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, idempotentHint=true and readOnlyHint=false, so the danger profile is structured. The description usefully adds a consent requirement and a timing window, but says nothing about what cancellation does to the order afterwards (irreversibility, refund, notification) and no output schema exists to cover the result.

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 action and timing constraint before the parameter and consent notes. 'Before making starts' relies on unexplained domain jargon ('making') that could be sharper, but no sentence 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 destructive, non-read-only mutation with no output schema, an agent still lacks the post-call picture: what is returned, whether the cancellation is reversible, and how a phone-mismatch failure surfaces. The core call requirements are covered, so it is adequate rather than 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 0% and both parameters are plain untyped strings, so the description carries the burden. It clarifies that phone is 'the phone number it was placed with' — i.e. a verification match — which is genuine added meaning, but it gives no format or normalization guidance (country code, digits only) and doesn't say what happens if the phone mismatches.

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') plus a timing scope ('before making starts'), which separates it from confirm_order, place_order and track_order. It doesn't name a sibling explicitly, so the differentiation is implicit rather than stated.

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?

'Only do this if the person asks' is an explicit consent gate, and 'before making starts' gives a clear precondition window. It stops short of naming alternatives (e.g. modifying rather than cancelling), but the when-to-use condition is unambiguous.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world behavior, so retry safety is covered. The description adds that a 6-digit code from the person is the confirmation credential, but says nothing about what confirmation changes (order state, notifications), what happens when the code is wrong or expired, or whether confirmation is reversible.

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 resource, and the second sentence is a non-redundant guard against code mangling. 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 state-changing tool with no output schema and 0% schema coverage, the definition leaves open what a successful confirmation returns or mutates and how failures surface. It covers the credential handling but not the post-call expectations an agent would want.

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 carry parameter meaning; it clarifies that 'code' is a 6-digit code received by the person and must be passed verbatim (no reformatting), which is genuinely useful. However, 'order_id' receives no explanation at all, so half the parameters remain 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?

States the verb 'confirm', the resource 'order', and the mechanism '6-digit code the person received', which distinguishes it from place_order/cancel_order/track_order without naming them. It stops short of explicitly routing against those siblings, keeping it at a solid 4.

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?

Contains no when-to-use or when-not-to-use guidance — nothing about when confirmation is appropriate versus track_order or cancel_order, nor prerequisites like order state. The sentence 'Use exactly the code they give you' is a parameter-handling instruction, not usage selection guidance.

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 description's job is lighter, and it adds real context: input is a natural-language want and the response surfaces sizes, colours, prices and making time. It stops short of describing result ordering, match quality, or what happens when nothing matches, which are the remaining behavioral gaps.

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, front-loaded with the action and scope, then the return contents. The example is short and directly clarifies the input style, so 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 one-parameter search with no output schema, the description covers the essentials: what it searches, what form the input takes, and roughly what comes back. Only minor gaps remain (no-match behavior and how to proceed to quoting/ordering), which are not strictly required 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 coverage is 100% for the single "request" parameter, so the baseline is 3. The description does add modest meaning by showing a concrete natural-language example ("something to hold my phone while I cook"), confirming the param is free-form conversational text rather than a keyword or ID.

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 ("what Unfactory can make"), so the agent knows this is a catalog lookup rather than a wish/order action. It does not explicitly name a sibling to distinguish itself from (e.g. get_quote for pricing an item), but the domain separation from the wish/order tools is clear from the wording.

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 when to use it — when you have a free-text description of a desired object — but never states when not to use it or points to alternatives. An agent must infer on its own whether get_quote or place_order is the correct follow-up rather than a second search.

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; the description adds the genuinely new fact that the quote_id expires in 24 hours and that the total includes delivery. It also imposes a human-in-the-loop obligation before ordering, which is behavioral context an agent cannot get from the annotations or schema.

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

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

Three short sentences ordered as purpose, return values, then the required follow-up action. Every clause carries information and nothing is repeated from the schema or 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 no output schema, the description steps in properly by naming the returned fields (quote_id, naira total including delivery, arrival day) and the validity window. What is missing is error behavior for mis-specified options and any note on whether delivery cost varies by quantity above one.

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?

At 67% schema coverage the schema already documents size, colour, quantity, makeable_id, and personalisation, and the delivery_state enum is self-explanatory. The description adds only the framing that options are "chosen" and the destination is a Nigerian state; it does not clarify what happens for invalid size/colour values or the quantity ceiling of 50.

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?

"Price one item with chosen options, delivered to a Nigerian state" gives a specific verb (price) and resource (item + destination), and the return clause names the three values produced. This is clearly distinguishable from ordering siblings such as place_order or confirm_order, and from find_makeables which supplies the id.

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?

"Show this to the person before ordering" establishes this as the pre-purchase step in the flow, which implies the ordering tool is the alternative. It does not explicitly name place_order or state when re-quoting is needed (e.g., after the 24-hour window lapses), so guidance is strong but not exhaustive.

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 write, open-world, non-idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: slot 1 is sealed, pricing depends on when the person joined, and payment happens only when the item is made.

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 core action, then organized by slot, and every sentence contributes operational detail. Despite being dense, it avoids filler and supports quick scanning.

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 15-parameter write tool with no output schema, the description covers the main purpose, slot-specific requirements, sourcing of makeable_id, and return/payment behavior. It is largely complete, though it could mention wish_token handling or other optional fields more explicitly.

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 73%, and the description meaningfully maps parameters to slots: slot 1 needs reason, slot 2 needs recipient_name, recipient_phone, recipient_city, giver_name, and recipient_note, and makeable_id should come from find_makeables. It adds conditional semantics not fully conveyed by the schema alone, though it does not cover every parameter such as wish_token or finishing_detail.

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

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

States a specific action and resource: saving one of the person's three founding wishes, with the three slot meanings laid out. It clearly distinguishes slot 1, slot 2, and slot 3, and references find_makeables as the source for makeable_id.

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

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

Gives clear usage context: this is for one of the three founding wishes, must start from a makeable_id from find_makeables, and slot 2 requires specific recipient details. It does not explicitly say when to choose this over siblings like add_wishes or start_three_wishes, so it is clear but not fully alternative-aware.

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 genuinely non-obvious behavior: results include a feasibility/makeability status and are ordered by how widely the wish is shared. It does not say how many wishes are returned or whether the list is paginated, which matters more here because there is no output schema to fill the gap.

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, no filler, and the core subject is front-loaded in the first clause. The second sentence is short and earns its place by explaining ordering. Only minor imprecision ('the things ... wish for most') keeps it from being maximally tight.

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

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

For a zero-argument read tool with no output schema, the description is the sole source of return-value information, and it covers the two key fields (the wish and its makeability) plus ordering. It omits result volume, pagination, and whether wishes appear with vote counts or metadata, which leaves an agent guessing about the shape of 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The schema is an empty object with full coverage, leaving no semantic 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 names a specific resource — the wishes Unfactory members share most — and adds a second dimension, whether each can be made yet. That distinguishes it from siblings like my_wishes or add_wishes, which are personal rather than aggregate. It stops short of naming an alternative outright, but the resource is unmistakable.

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: an agent can infer this is for browsing trending/popular wishes rather than recording or tracking one's own. There is no explicit when-to-use statement and no routing to alternatives such as find_makeables or my_wishes. 'Wishes many people share get made first' explains the ranking, not the selection criteria for calling 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=true and openWorldHint=false, so safety and scope are covered structurally. The description adds real value with the note that the first founding wish stays sealed and that discounts, queue position, and an invite link are included. It says nothing, though, about authorization, what happens with an invalid or expired token, or whether the data is the caller's own versus another person's.

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

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

A single dense sentence with no filler, and the sealed-wish caveat is placed inline where it matters. It is packed with parenthetical detail, 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?

With no output schema, enumerating the returned fields is genuinely useful and largely compensates on the response side. However, for a tool keyed on an undocumented token with no usage guidance, the description leaves out the input-side information an agent needs 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 single required parameter, wish_token, is never mentioned in the description. The agent gets no explanation of what the token is, where it comes from, or how it relates to the 'their' whose wishes are shown, which is the one piece of semantics the schema cannot supply.

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 verb is only 'Shows', and the rest of the sentence is a list of return values (founding wishes, wish list, discounts, place in line, friends, invite link) rather than a statement of what the tool does. It is clear this is a read of a person's wish status, but it never says whose wishes or how the caller is identified, and it does not distinguish itself from siblings like most_wished or add_wishes.

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 and no mention of any alternative. With siblings such as most_wished, add_wishes, and make_wish in the same namespace, an agent gets no signal about which one to pick or under what preconditions.

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 this as a non-readonly, non-destructive, non-idempotent, open-world write. The description adds meaningful behavior beyond that: an out-of-band message (WhatsApp or SMS) is dispatched to the recipient's phone, which is not derivable from the annotations or schema. It stops short of saying what happens if the same quote is ordered twice, which matters given idempotentHint=false.

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, zero filler, with the gating precondition front-loaded before the side-effect and follow-up. Every sentence carries a distinct instruction.

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 write tool with no output schema, the description covers the trigger condition, the primary effect, and the mandated follow-up call, which is enough to drive a correct multi-step flow. It is slightly incomplete on failure/repeat behavior and on the three undocumented 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 coverage is only 50%, so the description should carry weight for the undocumented parameters, but it mentions none of them. quote_id, recipient_name and city have no explanation anywhere, and the description does not clarify whether phone is the recipient's or the sender's, or how quote_id ties to get_quote.

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

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

States a specific verb and resource ('Creates the order') plus the observable side effect ('sends a 6-digit code ... by WhatsApp or SMS'). It is clearly distinguishable from the sibling confirm_order, which it names as the follow-up step.

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

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

Gives an explicit precondition ('Only call after the person has seen the quote and said yes') and an explicit next action ('Then ask them for the code and call confirm_order'). The agent knows both when to invoke this and what to do afterwards.

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 annotations only covering read-only, open-world, non-idempotent and non-destructive status, the description adds real behavior: it sends an SMS code, and the number's country determines the format. It does not state whether calling again resends or invalidates a code, what the expiry is, or whether the call returns anything that verify_wisher needs. These are meaningful omissions but not contradictions.

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: the action first, the phone-format caveat second, and the required follow-up third. Every sentence carries information the agent needs, and nothing is repeated.

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, non-destructive trigger tool with no output schema, the description covers the action, the input nuance, and the following step. The remaining gap is the return value: it does not say whether a reference or session identifier comes back, which an agent might expect to pass to verify_wisher.

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 single parameter is a bare string, but the description compensates by explaining that the phone can be from any country and needs a country code outside Nigeria. That covering of the only parameter's format and scope goes beyond the schema. It does not show an example format, so it stops short of a 5.

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 and resource: it begins the wishes flow and sends a 6-digit verification code to the member's phone. It clearly differs from sibling verify_wisher, which it names as the next step, but the phrase 'Begin a founding member's wishes' is slightly abstract until the second sentence gives the concrete 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 clearly gives the workflow: start here, get the code from the user, then call verify_wisher. It does not explicitly rule out other wish tools such as make_wish or add_wishes, and it does not say when not to use it, so it falls short of a full when/when-not/alternatives statement.

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 the phone must be "the phone number it was placed with," hinting at an identity/verification gate, but does not say what happens if the phone does not match the order or what the history 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 with zero filler: the outcome is front-loaded, and the prerequisite follows. Nothing is repeated from the schema or 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 simple read-only lookup with two scalar parameters and no output schema, the description covers the purpose, the return content, and both required inputs. The only gap is the failure mode when the phone does not match, which an agent would likely need to interpret errors.

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%, so the description must carry the parameter meaning, and it does clarify that phone must be the one the order was placed with rather than any contact number. It adds no format guidance (country code, digits only) for either identifier, leaving real ambiguity for a 0%-coverage 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?

States a specific verb and resource ("Get the status and history of an order") and names the returned content, which distinguishes it from siblings such as get_quote or cancel_order. It does not explicitly contrast itself with any sibling, which keeps it below 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 implies when to call it by naming the two identifiers required, which implies the caller already has an order in hand. It gives no explicit exclusions or alternatives (e.g. cancel_order or get_quote) for an agent that is unsure which order-related tool fits.

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 the safety profile (idempotent, non-destructive, closed-world, not read-only), so the bar is lower, and the description still adds real value by disclosing the full return payload an agent will need before calling make_wish. It does not say what happens when the code is invalid or expired, nor whether the token has a lifetime, which are meaningful gaps for an auth step.

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 action and then the return values, with no filler. The return-value list is dense but every item is something the agent needs to know. Minor inefficiency in listing outputs narratively rather than structurally.

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 absorbs the responsibility of describing what comes back, and annotations handle the safety semantics. For a three-parameter verification tool the coverage is nearly sufficient; the unexplained 'phone' parameter and the absence of any error/expiry behavior are the remaining 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 carries the burden and it only partially succeeds: it explains 'code' (the code the person received, and to pass it verbatim) and 'invite_code' (pass it when someone invited them). The required 'phone' parameter is never mentioned, leaving one of three parameters undocumented in both schema and 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 (check the code the person received) and enumerates what comes back, including the wish_token, founding number, existing wishes, queue position and invite link. That makes the tool's role as an identity/verification step clear, and it names make_wish and my_wishes as downstream consumers. It does not explicitly contrast itself with siblings like start_three_wishes, so it falls 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?

Usage is implied rather than stated: by saying it returns a wish_token for make_wish and my_wishes, an agent can infer this must be called first. The only explicit guidance is about argument fidelity ('use exactly the code they give you') and the conditional invite path. There are no stated preconditions, failure handling, or when-not-to-use conditions.

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