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

The description goes well beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=false. It explicitly warns that this write is UNVERIFIED and instructs the agent to inspect the confirmation preview before approving. It also details the confirmation mechanism, including the confirmToken usage, which is critical behavioral information.

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 dense yet efficient. It front-loads the primary purpose, then covers confirmation flow, unverified status, and parameter nuance in a well-organized manner. Every sentence carries essential information with no wasted words.

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

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

Given the tool's complexity (confirmation, two-step fallback) and lack of an output schema, the description explains the response flow (preview and confirmToken) and the caution about unverified behavior. It covers what an agent needs to call it correctly, though it does not specify the preview content or success response details, which is acceptable given the unverified nature.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds significant value by explaining the confirmToken's role in the two-step fallback, emphasizing that it must not be invented or reused, and clarifying when it is ignored. This goes beyond the schema's basic 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 clearly states the tool's action: 'Apply a coupon code to the account.' This is a specific verb and resource, and it is distinct from sibling tools like mhlb_apply_gift_card and mhlb_remove_coupon. The purpose is immediately obvious.

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

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

The description provides clear context about the confirmation flow and the two-step fallback, but it does not explicitly state when to use this tool versus alternatives or when not to use it. It implies usage for applying a coupon, but lacks explicit routing to or away from sibling tools.

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

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

Beyond annotations, the description discloses critical behavioral context: the confirmation requirement, the two-step token flow, and the important caveat that this write is UNVERIFIED and should be inspected via the preview before approving. This goes well beyond what readOnlyHint/destructiveHint alone convey.

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

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

The description is compact and front-loaded: the core action is stated first, followed by the confirmation mechanics and then the unverified-write warning. Every sentence carries necessary information without fluff.

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?

Despite lacking an output schema, the description explains the essential runtime behavior: confirmation prompt behavior, the preview and confirmToken returned on first call, the repeat-call requirement, and the safety warning. This is sufficient for an agent to invoke the tool correctly and safely.

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

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

Schema description coverage is 100%, so the schema already documents both 'code' and 'confirmToken' thoroughly. The description reinforces confirmToken's role in the two-step flow, but does not add substantial new parameter meaning beyond what the schema already provides.

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: 'Redeem a gift card code onto the account balance.' This clearly distinguishes it from siblings like mhlb_list_gift_cards and mhlb_apply_coupon without requiring the agent to infer from the name 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 clearly states what the tool does and the confirmation flow that must be followed, including the two-step fallback and the MCP_CONFIRM_MODE reference. It does not explicitly name alternatives or when-not-to-use conditions, but the distinct purpose and sibling names make the intended usage clear enough.

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

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

Annotations already mark this as destructive/non-read-only, and the description adds crucial context: it makes a real payment, requires prior checkout initialization, may require a two-step confirmation, and is explicitly marked as UNVERIFIED with a warning to inspect the preview before approving. This is exceptionally transparent about the operation's risk.

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?

Every sentence earns its place: the core action, prerequisite, card constraint, confirmation behavior, and verification warning are all essential. The description is dense but not bloated, and the safety-critical caveat about the unverified write is included without unnecessary 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 high-stakes payment tool with no output schema and no annotation detail beyond mutability and destructiveness, the description covers prerequisites, confirmation semantics, limitations, and risk warnings. It gives an agent enough to invoke the tool safely and to route the user through the confirmation step properly.

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%, and each parameter already has detailed meaning in the schema. The description adds some operational context around expectedTotal and the confirmToken flow, but it largely restates what the schema already documents rather than providing substantial new parameter-level insight.

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: 'PAY for the lunches in the cart' and immediately clarifies the real-world consequence: 'charges a real payment method.' It distinguishes itself from mhlb_init_checkout by requiring that tool as a prerequisite and positioning this one as the actual charging 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?

The description gives explicit workflow instructions: run mhlb_init_checkout first, read the returned total, pass it as expectedTotal, and only use a card already saved on the account. It also clearly states when the tool cannot be used (new card requiring a Stripe token unavailable server-side) and describes the confirmation flow for both supported and unsupported environments.

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 what readOnlyHint/destructiveHint provide, the description discloses the confirmation requirement, the two-step preview/confirmToken fallback behavior, and the unverified write status. The warning to inspect the preview before approving is especially valuable context.

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

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

Every sentence earns its place: goal, prerequisite, payment exclusion, confirmation protocol, and risk caveat. The information is front-loaded and there is no filler or repetition of schema content.

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 tool with no output schema, the description covers the invocation workflow, confirmation behavior, and trust caveat thoroughly. The only minor gap is that it does not describe what the final successful response contains, but the unverified-write warning makes that omission reasonable.

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

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

Schema description coverage is 100%, so the schema already documents the order model and confirmToken semantics. The description reinforces the quantity-editing workflow and repeat-call token rule but adds little meaning beyond the structured parameter descriptions.

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

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

The description states a specific verb-resource pair ('Place a lunch order into the cart') and clearly distinguishes this tool from mhlb_checkout, mhlb_get_order_form, mhlb_update_order, and mhlb_delete_order. It also names the prerequisite get_order_form flow, making its role 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?

It gives explicit direction to call mhlb_get_order_form first, send the returned model back with quantities set, and use mhlb_checkout for payment instead. It also explains both confirmation-mode invocation paths, so the agent knows exactly when and how to call this tool versus alternatives.

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

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

Beyond the annotations, the description warns that this write is UNVERIFIED and may not match the real API, and tells the agent to inspect the confirmation preview before approving. It also reveals the two-phase behavior where the first call returns a preview and confirmToken in non-elicitation clients.

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?

Every sentence earns its place: the action, the form prerequisite, the confirmation behavior, and the unverified warning. The warning is placed at the end but the critical operational steps are front-loaded.

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

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

For a mutating tool with no output schema and only basic annotations, the description covers the required pre-call step, the confirmation protocol, the repeat-token flow, and the unverified risk. An agent has enough context to invoke it correctly and cautiously.

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 100% schema coverage, the baseline is 3, but the description adds workflow meaning: the student object must come from the form tool with edits applied, and confirmToken must not be invented or reused. Most of this is complementary to the schema rather than purely redundant.

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 ('Add a student to the account') and distinguishes the tool's write role by naming mhlb_new_student_form as the source of the model to submit. This clearly separates it from sibling get/update/delete student tools.

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

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

It explicitly states the prerequisite workflow: call mhlb_new_student_form first, fill the model, then send it back. It also gives precise when-to-use guidance for the confirmation fallback, including that a repeat call with confirmToken proceeds only after user approval.

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 discloses that refund behavior is outside the tool's control, that confirmation is required, and that the request shape is UNVERIFIED against a live account and was derived from the web app's compiled API client. This meaningfully supplements the annotations' destructiveHint and should change how an agent executes and approves the 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?

The description is longer than average, but every sentence earns its place: purpose, refund caveat, confirmation mechanics, fallback behavior, and the unverified-write warning. The core action is front-loaded, and the safety warnings appear before an agent would act.

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 write with no output schema, the description explains the full confirmation flow, what a fallback first call returns (preview plus confirmToken), and what to inspect before proceeding. Parameter details are fully covered by the schema, and the annotations cover destructive intent, so no critical operational information 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%, and the parameter-level descriptions are already rich: confirmToken explains the exact two-step protocol, eventDate specifies the format, and isSubscribed gives per-tool defaults. The tool description adds no parameter-specific meaning beyond that, so the baseline 3 for high schema coverage 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 opens with 'Cancel a lunch order', a specific verb and resource that unambiguously defines the operation. It also clarifies scope by noting that refund behavior is external and by distinguishing this cancellation tool from the subscription-focused sibling mhlb_unsubscribe_order.

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

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

The description gives clear process guidance for confirmation: use the client-supported prompt when available, or the two-step preview/confirmToken fallback otherwise, with explicit rules about never inventing or reusing the token. It does not explicitly enumerate when to prefer this over mhlb_unsubscribe_order, but the schema's isSubscribed description hints at that split, so the usage context is clear if 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 signal destructiveHint=true, but the description goes much further: it discloses irreversibility, cascading deletion of order history, the confirmation prompt vs. confirmToken fallback, and the fact that the write is UNVERIFIED against a live account. This is exemplary transparency for a high-risk mutation.

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 dense but every sentence earns its place: the action, the irreversible consequence, the confirmation expectation, the fallback flow, and the unverified-write warning are all present with no filler. The most important scoping facts appear early, making the risk profile immediately visible.

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 tool with two parameters and no output schema, the description covers everything needed: what gets deleted, how confirmation works, what the fallback response shape is, and that the agent must inspect the preview before approving. Nothing critical is missing for safe invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents studentId and confirmToken, including safety rules like 'never invented, never reused.' The tool description reinforces the confirmToken flow but adds little beyond the schema's own parameter descriptions. Baseline 3 is appropriate because the schema carries the semantic load.

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

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

The description clearly states a specific verb and resource: 'Remove a student from the account.' It also goes beyond a simple label by explaining the consequence ('order history goes with them') and distinguishing this destructive action from less final operations. Siblings like update_student or delete_order are easy to tell apart.

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 makes the intended use obvious: deleting a student, with strong emphasis on the irreversible nature and the need for user confirmation. It does not explicitly contrast with alternatives such as update_student, but it provides clear operational context and a precise two-step confirmation workflow, so an agent can decide when to invoke 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 cover readOnlyHint and openWorldHint, so the safety profile is established. The description adds useful behavioral context beyond the schema: account scope, date range, and the specific per-student statuses returned (open, ordered, paid, cart, subscribed, closed). It does not detail response structure or pagination, but that is less critical for a read-only calendar summary.

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

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

Two sentences with no filler. The main action and scope are front-loaded, and the status list is compact but informative.

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

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

For a read-only tool with two simple required date parameters and no output schema, the description orients the agent well: it names what data is returned and per whom. It stops short of specifying the exact response shape, but the enumerated statuses are enough for correct use.

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

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

Schema coverage is 100%, so the parameter descriptions already document the start and end dates. The tool description only refers to 'a date range' and does not add semantic detail beyond what the schema provides.

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 ('Get the lunch calendar') and clearly defines scope: date range and per-student day statuses. It does not explicitly contrast this tool with siblings like mhlb_print_calendar or mhlb_get_day, so it misses the full 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 use the tool by saying it reflects the Lunch Calendar page, but it gives no explicit when-to-use guidance or alternatives. There is no mention of preferring mhlb_get_day for a single day or mhlb_print_calendar for a printable version.

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 readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. The description adds value by specifying scoping (unpaid lunches, filterable) and the concept of 'cart' vs paid orders. It does not contradict annotations. It adds useful behavioral context beyond annotations.

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

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

The description is a single, front-loaded sentence that clearly states the core purpose and then lists filters. No wasted words; every phrase 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?

Given the tool has no output schema and simple parameters, the description is sufficient for an agent to know what it returns (cart contents) and when to invoke it. It does not detail return format, but that's acceptable for a simple get operation with readOnlyHint.

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 all three parameters have descriptions in the schema. The description adds minimal meaning beyond schema, but the schema already covers semantics. Baseline 3 is appropriate.

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

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

The description states a clear purpose: retrieving the shopping cart (lunches not yet paid for) with filtering options. It distinguishes from siblings like mhlb_list_transactions or mhlb_get_order by focusing on the cart. However, it does not explicitly name siblings it is not, so it could be clearer in 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?

The description implies when to use: when needing unpaid lunches in the cart, with optional filters. It does not explicitly state when not to use or alternatives (e.g., use mhlb_get_order for paid orders). Lacks explicit exclusions, but the context is reasonably clear.

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 provide readOnlyHint=true, so the safety profile is covered. The description adds that the tool returns valid filter values and the default selection, and positions it as a pre-filter step. However, it does not describe the response shape or how the optional parameters affect the result, so some behavioral detail is still missing.

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

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

The description is two compact sentences with no filler. The primary purpose is front-loaded, and the usage instruction is short and relevant. Every sentence 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 read-only tool with no output schema and fully described optional parameters, the description conveys what the tool returns (periods, status tabs, default selection) and when to call it. The only minor gap is the implicit response shape, but the conceptual return contents are sufficiently clear.

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 all three parameters (period, tabName, studentId) are already documented in the schema. The description does not add parameter-level detail beyond framing the tool's purpose, which matches the baseline for full schema 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?

The description names a specific action ('Get the valid filter values') on a specific resource (mhlb_get_cart), and details the contents: ordering periods and status tabs, including the default selection. This clearly distinguishes it from sibling mhlb_get_cart, which presumably retrieves the cart itself.

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

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

The phrase 'Call this before filtering the cart' gives a clear and actionable context for when the tool should be used. It does not explicitly name alternatives or exclusions, but the relationship to mhlb_get_cart makes the intended workflow obvious.

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 provide readOnlyHint=true, so the read-only nature is covered. The description adds 'if any', indicating the coupon may be absent, which is a behavioral nuance beyond the annotation. However, it does not specify what happens when no coupon exists (null, empty, etc.), and it doesn't disclose any other behavioral traits. The addition is modest.

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

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

The description is a single concise sentence that front-loads the verb 'Get' and specifies the resource and scope. There is no redundant wording, and every word contributes meaning. It is appropriately minimal for a zero-parameter read tool.

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 getter with no output schema, the description is largely sufficient. It states what is returned (the coupon) and that it may be absent. It doesn't detail the coupon structure, but that is not necessary for invoking the tool correctly. The annotations cover safety, and the sibling tools provide context. A small gap is the lack of explicit return-type clarification, but overall it is complete enough.

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 has zero parameters, so the baseline is 4 per the rubric. There is no parameter information to add beyond what the schema provides, and the description correctly avoids inventing any. This is a non-issue.

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 'Get' and identifies the resource 'coupon' along with scope 'currently applied to the account, if any'. It clearly distinguishes from sibling mutators mhlb_apply_coupon and mhlb_remove_coupon, so an agent can immediately tell this is a read-only retrieval.

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

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

The description implies usage as a getter, but does not explicitly state when to use it versus alternatives like apply/remove. There is no mention of 'use this to check the current coupon before applying' or any exclusion. The context is clear from the name and sibling list, but the guidance is implied rather than explicit.

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, covering safety and external dependencies. The description adds the nature of the returned data (items, prices, etc.), which is output content rather than behavioral context. It does not disclose potential side effects or limitations beyond what annotations imply, so it meets the baseline without enriching beyond the structured metadata.

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

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

The description is a single, focused sentence that leads with the action and resource, then lists the detail fields. There is no fluff or repetition; every word 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 simple read tool with two parameters and no output schema, the description covers the essential data content (items, sizes, quantities, add-ons, prices) and the date scope. It lacks explicit error scenarios or prerequisites beyond the schema's studentId hint, but overall it is adequate for an agent to call 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 100% for both parameters. The schema already explains studentId as 'Student id from mhlb_list_students' and date as 'The day to look at (YYYY-MM-DD)'. The tool description adds no additional parameter meaning, 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 clearly states a specific verb (Get) and resource (what a student has ordered on a specific date), and enumerates the returned fields (items, sizes, quantities, add-ons, prices). This distinguishes it from siblings like mhlb_get_order (single order) and mhlb_get_cart (current cart) by emphasizing the date qualifier.

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

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

The phrase 'one specific date' gives clear context for when to use this tool, implying it is for a single day's data for a known student. It does not explicitly name alternatives or state when not to use, but the description provides sufficient situational framing for an agent to select it versus other getters.

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 description need not repeat safety. It adds useful context about what is returned (orderable menu, prices, deadline) and its role in ordering, but does not disclose any additional behavioral constraints such as deadline enforcement, data availability, or error behavior. 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?

Two sentences with no filler. The first sentence front-loads the action and key data points; the second provides the workflow context. Every word contributes to the agent's understanding.

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 no output schema, the description compensates by listing the major return categories and clarifying the tool's place in the order flow. It does not mention error conditions or the exact output format, but for a read-only, two-parameter menu lookup the provided detail is largely sufficient.

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

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

Schema coverage is 100%, so the schema already documents both parameters: date as the lunch date and studentId as sourced from mhlb_list_students. The description's 'one student on one date' merely restates the parameter scoping without adding format or dependency details. 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 opens with 'Get the orderable menu for one student on one date' — a specific verb and resource — then enumerates the returned contents (vendor, items, sizes, add-ons, prices, ordering deadline). It also notes this is the read half of placing an order, clearly differentiating it from order creation and other menu-adjacent tools like mhlb_get_day or mhlb_get_order_form.

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

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

The phrase 'This is the read half of placing an order' gives clear contextual guidance: this tool should be used before any order creation or update. It does not explicitly name alternative tools or exclusion conditions, but the context is unambiguous for an agent navigating the ordering workflow.

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 useful context that the return value is shaped specifically for mhlb_update_order. It doesn't disclose error behavior or parameter selection rules, but with annotations this is adequate.

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 single sentence is front-loaded with the core action ('Get an existing order in editable form') and the second clause about update_order is also informative. Every word earns its place; no fluff 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 read-only getter with full schema coverage and safety annotations, the description is adequate. It omits explanation of how the three optional parameters interact (e.g., whether orderId alone is sufficient) and assumes the agent knows update_order's input shape, but the explicit link to update_order fills the most important gap.

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

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

Schema description coverage is 100% and all three parameters have individual descriptions. The tool description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states a specific verb ('Get') and resource ('existing order') and adds that the result is in an 'editable form' intended for mhlb_update_order. This distinguishes it from sibling tools like mhlb_get_order_form, though not explicitly. Minor gap: it doesn't contrast with all potentially confusing siblings.

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

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

The phrase 'the model mhlb_update_order expects back' strongly implies the intended use case: fetch an order to pass to the update tool. However, it does not explicitly say when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions.

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 known. The description adds valuable behavioral context: it returns a pre-populated structure with available items, and that the structure is exactly what mhlb_create_order expects. This goes beyond the annotations without contradicting them.

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

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

A single, dense sentence that front-loads the primary action and key value proposition ('pre-populated with the available items'). No filler or redundant phrasing. Every word 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?

The tool is simple (2 required params, no nested objects, no output schema). The description explains what the output is (the structure for mhlb_create_order) and its key trait (pre-populated items), which is sufficient for an agent to know how to use it. It could mention the exact content of items, but that is likely available from mhlb_get_menu. Overall, complete for its complexity.

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%: both parameters (eventId and studentId) have clear descriptions including their source tools (mhlb_get_menu/mhlb_get_calendar and mhlb_list_students). The description does not add extra meaning about parameters beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('Get') and a precise resource ('blank order model for a student on a specific lunch event'), and explains its purpose ('exact structure that mhlb_create_order expects back'). This clearly differentiates it from siblings like mhlb_get_order (existing order) and mhlb_get_student_form (different form).

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 the use case: when you need a blank form to later create an order. It references mhlb_create_order as the consumer, giving clear context. It does not explicitly mention alternatives or when not to use it, but the 'blank' vs 'existing' distinction is implicit. No exclusion criteria, but the purpose is strong enough to guide selection.

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

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

Annotations already mark it readOnlyHint=true, and the description adds a meaningful behavioral contract: it returns an editable profile shaped for mhlb_update_student. It does not describe edge cases like missing student, but the read-only annotation lowers the bar.

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 primary action and target are front-loaded, and the second sentence adds the most decision-relevant detail: compatibility with mhlb_update_student.

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 simple one-parameter read tool. The description lists the return content and connects it to the update flow, which is sufficient context despite the absence of an output schema. Minor omissions like not-found behavior do not significantly harm usability.

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 only parameter, studentId, is already documented as coming from mhlb_list_students. The description adds little beyond 'one student', so the schema carries the semantic weight.

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 editable profile for one student', then enumerates the fields (school, grade, teacher, delivery location, allergies, dropdown options). This distinguishes it from mhlb_list_students and mhlb_new_student_form.

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

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

The phrase 'Returns the exact model that mhlb_update_student expects back' clearly situates this tool as the fetch step before updating a student. It does not explicitly say when not to use it or name alternatives, but the intended context is clear.

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 and externally-changing nature of the data is covered. The description adds context about what configuration fields are returned, but it does not disclose additional behavioral constraints such as authentication requirements, error cases, or data freshness. No contradiction with annotations.

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

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

A single, front-loaded sentence states the resource and immediately explains the two pieces of information returned. There is no filler and no redundant restatement of the tool name.

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 no-argument, read-only getter, the description covers the main purpose and roughly describes the response content. It is slightly vague about what 'terms' means and does not distinguish itself from mhlb_list_subscriptions, but the simplicity of the tool makes this a minor gap.

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

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

The tool takes zero parameters, so there is nothing for the description to add beyond the input schema. The baseline for 0 parameters is 4, and the description appropriately focuses on the return content instead of parameter details.

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 ('Get') and a specific resource ('the account's subscription configuration'), then clarifies what that means: whether recurring ordering is on and the terms. It does not explicitly contrast with the sibling mhlb_list_subscriptions, 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?

There is no guidance on when to use this tool versus alternatives like mhlb_list_subscriptions, mhlb_set_subscription_enabled, or mhlb_unsubscribe_order. The verb 'Get' implies read-only usage, but no explicit context, exclusions, or alternatives are provided.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it's a safe read. The description adds the context that it returns line-item detail (lunches paid for), which is useful but doesn't disclose additional behavioral aspects like error handling or authentication requirements. With annotations covering the read-only safety, a score of 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?

The description is a single clear sentence, front-loaded with the action and scope. Every word adds value.

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

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

Given the tool's simplicity (one parameter, read-only, no output schema), the description sufficiently explains what it does and what it returns. It could mention the response structure more explicitly, but the 'line-item detail' phrasing gives adequate context. Minor gaps exist around exact response format, but they are not critical.

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

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

The input schema fully describes the transactionId parameter, including its source ('id' field from mhlb_list_transactions). The tool description adds no additional parameter information beyond the schema, so with 100% coverage the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('get') and resource ('transaction'), and further specifies 'line-item detail' and explains what that means ('which lunches it paid for'). This clearly distinguishes it from sibling tools like mhlb_list_transactions which lists transactions, and mhlb_get_order which deals with orders.

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

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

The description implies usage: to retrieve details of a single transaction, presumably after listing transactions. However, it does not explicitly name alternative tools or give when-to-use vs when-not-to-use conditions, so guidance is implied rather than stated.

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

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

The description adds beyond annotations by explicitly stating it is read-only and 'never returns the credential itself', a safety-critical behavior. It also discloses that it makes one authenticated request and reports round-trip time, which are behavioral details not captured by the annotations. This is valuable transparency.

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 logically structured into action, outputs, and usage, and the essential details are front-loaded. It is slightly verbose with the repetition of the hostname and the long enumeration of failure modes, but every sentence earns its place. It could be tightened but remains clear and readable.

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 parameters and no output schema, the description is complete: it explains what the tool does, what it reports, the safety guarantee, and when to use it. It covers the key return values (credential source, acceptance, round-trip time, and error hint) in plain language, so an agent has everything needed to invoke 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?

There are zero parameters, and the schema is an empty object, so there is nothing to document. The description correctly focuses on behavior rather than parameters, and the baseline for 0 params is 4. It adds no parameter-specific meaning because none exist.

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 (resolves credentials and makes an authenticated request to a named host) and explicitly reports the diagnostic outputs. It also distinguishes itself from siblings by framing the tool as a failure-diagnosis tool ('Call this when a real tool fails and you want to know which hop broke'). This gives clear, unambiguous purpose.

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

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

It provides a clear, explicit trigger: 'Call this when a real tool fails and you want to know which hop broke.' However, it does not name alternative tools or state when not to use it, so it lacks the full when-not/alternatives guidance. The context is clear enough for an agent to decide, 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 mark readOnlyHint=false, so it's a write; the description clarifies it does not charge but is still a write step. It discloses the confirmation prompt behavior and the two-step fallback with confirmToken, and adds a critical UNVERIFIED warning about the request shape. This goes well beyond the annotations and gives the agent actionable risk awareness.

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 dense but well-organized: purpose first, then confirmation flow, then a safety warning. Every sentence carries information; no filler, though it is slightly longer than minimal due to the necessary confirmation and unverified warnings.

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

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

Given the confirmation complexity and the UNVERIFIED warning, the description covers the behavior an agent needs: what it returns, that it's a pre-checkout step, how confirmation works, and the risk. No output schema, but return values are listed. It's complete for this tool, though it could mention what happens if the cart is empty or invalid.

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% with detailed descriptions for each parameter, including confirmToken's special semantics. The description itself doesn't add parameter-specific meaning beyond what the schema provides, so it stays at the baseline for high schema 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?

States a specific verb and resource: 'Start checkout for the cart' and lists the returned data (order summary, totals, taxes, credits, payment methods). Explicitly distinguishes from sibling mhlb_checkout by calling itself 'the read step before mhlb_checkout', so an agent can tell them apart without inspecting schemas.

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

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

Clearly indicates it is the first step before mhlb_checkout and does not charge. Describes the confirmation flow and references MCP_CONFIRM_MODE, giving explicit sequencing guidance. It doesn't mention when to use a non-checkout alternative like mhlb_get_cart, but the purpose is distinct enough that the agent can infer the right context.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds valuable behavioral context: codes are masked by default and revealCodes exposes redeemable money, signaling a security-sensitive operation. No contradiction.

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

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

Two sentences with no filler. The main action and output are front-loaded, followed by the precise conditional for the optional parameter.

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

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

For a read-only list tool with one optional boolean parameter and no output schema, the description covers the action, the masking behavior, and the reveal condition. Nothing an agent needs to call 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 covers revealCodes with 100% description coverage, explaining the default and security note. The description adds the conditional usage context ('only when the user needs a full code'), going slightly beyond the schema.

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

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

States a specific action (List), resource (gift cards), scope (on the account), and key output details (balances, status, masked codes). Clearly distinct from siblings like mhlb_apply_gift_card which operates on gift cards differently.

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?

Provides explicit conditional usage for revealCodes ('only when the user needs a full code'), which is direct guidance. Does not name alternatives, but no sibling list-gift-cards tool exists, so the context is sufficient.

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 already provided, the description adds useful behavioral context beyond the annotation: it discloses that results include inactive profiles and unaccepted invites, and that the student id is a dependency for other tools. This helps the agent interpret the returned data correctly. No contradiction with annotations.

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

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

Two sentences with no fluff: the first lists the output fields, the second explains downstream utility. Every sentence earns its place and the key action is front-loaded.

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

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

For a zero-parameter list tool with no output schema, the description covers what data is returned and why it matters for later tools. It does not specify exact response envelopes or pagination, but for this simple list operation the information is largely sufficient.

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

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

There are zero parameters and schema description coverage is 100%, so the baseline is 4. The description adds no parameter details because none are needed; it focuses on output meaning instead.

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 ('List') and a clear resource ('the students on the account'), then enumerates the returned fields: id, first name, school, grade/teacher, order presence, and inactive/invite status. This makes it easy to distinguish from siblings like mhlb_list_transactions or mhlb_get_calendar.

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 sentence 'The student id feeds every calendar and ordering tool' gives implicit but strong guidance: call this tool first to obtain student IDs before using downstream tools. It does not explicitly name alternatives or say when not to use it, but the context is clear enough for 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?

readOnlyHint already covers safety; the description adds that these are recurring orders that will be placed and charged automatically, giving context about the nature of the listed items. It does not cover auth, rate limits, or pagination, but adds value beyond 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 sentence with no wasted words; the verb and resource are front-loaded, and the appositive efficiently defines the key term. The description is appropriately sized and easy to parse.

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

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

For a read-only list tool with one optional parameter fully documented in the schema, the description is sufficient. It clarifies what a subscription is and that the list is of upcoming ones. It does not mention response format, but that is not required without an output schema.

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

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

Schema coverage is 100% and the schema describes 'period' as 'Ordering period to scope to.' The description adds no parameter-specific information, so the baseline of 3 applies because the schema carries the full parameter semantics.

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

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

States a specific verb and resource ('List upcoming lunch subscriptions'), clarifies the domain term via the appositive 'recurring orders that will be placed and charged automatically', and is clearly distinct from sibling list tools such as list_transactions and list_gift_cards.

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 the use case of viewing upcoming auto-charged orders, but it does not explicitly state when to use this tool over alternatives like mhlb_list_transactions or mhlb_get_subscription_settings. No when-not-to-use or alternative routing is provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds a hint about the returned fields, but it does not disclose default scoping, how period/student filtering affects results, ordering, or pagination.

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 action front-loaded and no filler. Every phrase earns its place by adding information about the resource or the returned content.

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

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

The tool is simple and read-only, and the schema explains both optional parameters. However, with no output schema, the description leaves the default scope and exact result shape less explicit than it could be, making it adequate but not 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?

Both parameters have 100% schema description coverage, so the schema already explains period and studentId. The description adds no parameter-level meaning beyond what the schema provides.

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?

Uses the specific verb 'List' with the resource 'payment transactions' and enumerates the returned fields (date, amount, and what was paid for). This clearly distinguishes it from singular/inspection siblings like mhlb_get_transaction and mhlb_print_transaction.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance and names no alternatives. It simply states the operation, leaving an agent to infer from the name that this is the enumerating tool versus mhlb_get_transaction.

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 mark the tool as readOnly, and the description's 'Get' wording is consistent with that. The description adds useful context by naming the contents of the response (blank profile plus dropdown options), but it does not go deeper into response shape, potential variability, or any other operational behavior. This is acceptable given the simple read-only nature, but not exceptionally transparent.

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

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

The description is a single, focused sentence that front-loads the core action and result, then adds the downstream usage ('pass to mhlb_create_student'). No filler or redundant restatement of the tool name.

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 form-retrieval tool, the description is complete: it says what the tool returns, that the result is blank/ready to fill, and how it should be consumed. Without an output schema, it still gives enough context for an agent to invoke the tool confidently and chain 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?

The input schema is empty, so there are no parameter semantics to document. Per the baseline for zero-parameter tools, the description does not need to add parameter-level detail, and it does not omit anything relevant.

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 ('Get') and a specific resource ('blank student profile plus school/grade/teacher dropdown options'), and further clarifies the purpose by linking it to mhlb_create_student. The word 'blank' and the create-student linkage distinguish this tool from the sibling mhlb_get_student_form without needing to open any schema.

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

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

The description clearly implies when to use this tool: when preparing to create a new student, retrieve the blank profile and dropdown options, then pass the result to mhlb_create_student. It does not explicitly rule out alternatives like mhlb_get_student_form, but the blank/new orientation provides sufficient context.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral detail: it writes the PDF to disk and returns a path, with an inline option for base64 bytes. This goes beyond the annotations and clarifies the side-effect profile without contradicting them.

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

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

Two sentences, zero filler. The first sentence front-loads the core purpose (generate PDF for date range), and the second covers output behavior and the inline option. Every word 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?

Given the five parameters, three of which are required, and the absence of an output schema, the description adequately explains what the tool returns (path or inline bytes). It also covers the side effect of writing to disk. It does not mention error conditions beyond what the schema already notes (e.g., empty studentIds fails), but that is already documented. No critical missing context for correct invocation.

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

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

Schema description coverage is 100% — every parameter (startDate, endDate, studentIds, inline, filename) has a description. The tool description reiterates the inline behavior and file-writing but adds no new meaning beyond the schema. Baseline of 3 is appropriate because the schema carries the semantic load.

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

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

The description states a specific verb ('Generate') and a specific resource ('printable lunch calendar PDF'), and the date range scope. It clearly distinguishes from the sibling mhlb_get_calendar (data retrieval) and other print tools like mhlb_print_orders and mhlb_print_transaction, even though it doesn't name them explicitly.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The description explains what it does but not when an agent should prefer it over mhlb_get_calendar or the other print tools. It does not mention conditions like needing a PDF versus data, or exclusions.

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

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

Annotations only provide readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds valuable behavioral details beyond those: the endpoint fails if studentIds is empty and also fails if no order matches the date/status. This helps an agent anticipate errors without contradicting the annotations.

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

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

Three sentences, no filler. The primary purpose is front-loaded, followed by critical constraints and a pointer to the data source. Every sentence contributes value.

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

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

For a 5-parameter tool with no output schema and modest annotations, the description covers purpose, input source, key failure modes, and scope. It does not explain the inline/filename output behavior, but the schema fully covers those, so nothing essential 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 coverage is 100%, with every parameter already documented (date format, inline base64, filename default, studentIds minItems, orderStatus const values). The description reinforces studentIds being required and failure-prone, but does not add new semantic information beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Generate the printable order-details PDF') and immediately scopes it to 'a single lunch date,' which distinguishes it from sibling print tools like mhlb_print_calendar and mhlb_print_transaction. The resource and scope are unambiguous.

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 instructs where to obtain the required inputs ('Get both from mhlb_get_calendar') and flags the single-date constraint. It does not explicitly name alternatives or say when not to use the tool, but the usage context is clear enough for an agent to route correctly.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the tool may create a file but not destroy data. The description adds a key behavioral quirk: 'the endpoint renders that record, it does not look one up by id', which is beyond the annotations. This clarifies the tool's dependency on the passed object, adding value.

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

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

Two sentences with zero waste. The main action and critical caveat are front-loaded, making it easy to scan. Every word 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 simple tool with fully documented parameters and no output schema, the description is complete enough for an agent to call it correctly. It covers the essential usage and the one non-obvious behavior. It doesn't mention optional parameters, but those are in the schema, so the description doesn't need to repeat them.

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

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

Schema coverage is 100%, so all four parameters are documented. The description reinforces the 'transaction' parameter by stating to pass the object from mhlb_get_transaction, but this is largely redundant with the schema description. It adds no new meaning for the other parameters, so it meets the baseline but doesn't exceed 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 description states a specific verb ('Generate') and resource ('printable receipt PDF for one transaction'), and distinguishes itself from siblings like mhlb_get_transaction (which fetches data) and mhlb_print_orders (which prints multiple). The added 'does not look one up by id' further differentiates from any id-based 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 clearly instructs to pass the transaction object from mhlb_get_transaction, which gives the context for when to use it. It doesn't explicitly state alternatives or when not to use it, but the requirement of having a transaction object is implicit. Could be improved by naming mhlb_print_orders for batch printing, but the guidance is sufficient.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint false), the description discloses a critical behavioral fact: the write is UNVERIFIED, its request shape was derived from compiled API client code, and it has not been exercised against a live account. It also warns the agent to inspect the preview before approving, which is significant transparent context.

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

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

The description is front-loaded with the core purpose, followed by the essential confirmation mechanics and a necessary risk warning. Every sentence carries required information, and there is no filler or repetition of the 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?

Given there is no output schema, the description sufficiently outlines the expected two-step behavior and the confirmToken handoff. It references MCP_CONFIRM_MODE and warns to inspect the preview. It does not spell out edge cases like 'no coupon applied,' but the confirmation flow and unverified-write warning cover the most important operational context.

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

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

Schema coverage is 100% and the confirmToken parameter is already richly documented in the input schema. The description adds value by explaining the two-phase return behavior—first call returns preview and confirmToken, repeat call with token proceeds—which gives the parameter operational meaning beyond the schema text.

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 clear, specific statement: 'Remove the coupon currently applied to the account.' This identifies the action (remove), the resource (coupon), and the scope (currently applied to the account), making it unambiguous and inherently distinct from related siblings like apply_coupon or get_coupon.

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 explicit, actionable usage guidance for the confirmation flow: prompt when the client supports it, otherwise first call returns preview/confirmToken, and only a repeat call with that token proceeds. It does not explicitly compare against sibling tools, but the unique action and 'currently applied' scope make the intended use clear.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, but the description adds crucial context: it discards a cached token (a specific action) and explains the consequence (next call re-authenticates). This goes beyond the annotations and clarifies the exact behavioral effect without contradicting them.

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

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

The description is two sentences with zero waste. It front-loads the action ('Discard the cached token'), immediately explains the purpose, and then provides the usage conditions. Every word 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?

Given the tool's simplicity (no parameters, no output schema), the description fully covers what the tool does, why it exists, and when to invoke it. There is no missing information an agent would need 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?

The tool has zero parameters, and the schema is empty. The description provides no parameter details (none needed). With 0 parameters, the baseline is 4, and the description adds nothing that would lower it. It's appropriate that no parameter information is given.

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 ('Discard') and a specific resource ('cached My Hot Lunchbox access token'), and explains the effect ('so the next tool call signs in again'). It clearly distinguishes itself from the sibling tools, which are all operational actions; this is the only session-management 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?

The description explicitly states when to use it: 'after changing credentials, or if calls start failing with stale-session errors.' This gives clear, actionable conditions with no ambiguity. No alternative tool exists for this purpose, so no need to mention alternatives.

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

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

The description discloses the confirmation behavior, including the two-step fallback with confirmToken, and warns that the write is UNVERIFIED with a request shape derived from compiled API client. This goes well beyond the annotations (readOnlyHint=false, destructiveHint=true) by explaining the exact behavior and risk. No contradictions with annotations.

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

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

The description is dense but every sentence carries critical information: purpose, confirmation flow, fallback mechanism, and the unverified warning. It is front-loaded with the core action and the warning is placed last. No fluff 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 write tool with a confirmation flow and an unverified implementation, the description covers all necessary operational details: the two-step process, the meaning of confirmToken, and the caution to inspect the preview. It also references MCP_CONFIRM_MODE for further context. No output schema exists, so return values aren't required, and the description doesn't claim them.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds meaning by explaining that 'enabled=true' means future lunches are ordered and charged automatically, and it elaborates on confirmToken usage, including never inventing or reusing tokens. This provides context beyond the bare schema definitions.

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

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

The description clearly states the tool's action: 'Turn recurring lunch subscriptions on or off for the account,' specifying both the verb and the resource. It distinguishes itself from sibling tools like mhlb_get_subscription_settings (read) and mhlb_list_subscriptions (list) by focusing on the write operation. The purpose is immediately clear and unambiguous.

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

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

The description provides explicit context on when to use the tool: to change subscription status, and it details the confirmation flow. However, it does not explicitly name alternatives or state when not to use this tool, though it's implied by the action. The note about inspecting the confirmation preview before approving is a useful safety guideline.

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 mark the tool as destructive, and the description goes further by stating the write is UNVERIFIED and instructing the agent to inspect the confirmation preview before approving. It also discloses the confirmation fallback mechanism, adding behavioral context beyond the annotations.

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

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

Two focused sentences plus a concise warning note. Every sentence serves a purpose: the first states the action and confirmation behavior, the second highlights risk and preview inspection. No filler or redundancy.

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

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

The description covers the confirmation flow, the unverified status, and the need to inspect the preview. It lacks a description of the final success response, but given the detailed schema and annotations, the tool is adequately specified for an agent 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 coverage is 100%, so all parameters are already documented. The description adds little beyond the schema—it mentions confirmToken in the flow but doesn't provide new semantics. Baseline 3 is appropriate since 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?

The description states a specific verb ('Stop'), a resource ('a recurring subscription for a specific lunch order'), and clearly distinguishes it from siblings like mhlb_delete_order and mhlb_set_subscription_enabled. The confirmation flow is also mentioned, leaving no ambiguity about what the tool does.

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

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

The description explicitly explains when to use the tool (to stop a subscription) and details the two-step confirmation process, including when to pass confirmToken. It doesn't explicitly contrast with alternatives, but the purpose is clear enough that an agent can decide appropriately.

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 only mark it as a write (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description carries the real burden and does so thoroughly: whole-order replacement semantics, the dual confirmation paths (client prompt vs. preview+confirmToken fallback), and the critically honest UNVERIFIED warning that the request shape was reverse-engineered from a compiled API client and never exercised against a live account. This materially changes how an agent should behave (inspect preview before approving).

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?

Five sentences, zero filler, with critical operational facts front-loaded: purpose, then prerequisite workflow, then confirmation mechanics, then the risk warning. The UNVERIFIED note is flagged with a clear 'NOTE:' marker. For a write tool with a confirmation flow and a schema, this density is justified — every sentence 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?

This is a complex write operation with a nested object param, no output schema, and a subtle two-step confirmation flow — the description covers all of it: the operation semantics, the prerequisite read call, both confirmation paths, the phase-1 response shape ('preview and a confirmToken'), and the unverified risk. The schema covers the remaining parameter details at 100%, so nothing an agent needs to invoke 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%, so the baseline is 3 — the schema already documents both the order model and the confirmToken protocol well. The description adds value by explaining the replace-the-whole-order workflow ('send that model back with your edits') and by spelling out the token's lifecycle rules (never on first call, never invented, never reused) in the context of the two-step fallback, which helps an agent know when the parameter is even relevant.

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?

Opens with a specific verb and resource: 'Change an existing lunch order.' It goes further and distinguishes this update from sibling create/delete/unsubscribe operations by stating the replace-whole-order semantics ('the endpoint replaces the whole order'), so an agent can tell it apart from mhlb_create_order, mhlb_delete_order, and mhlb_unsubscribe_order without opening their schemas.

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

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

Gives an explicit prerequisite workflow: 'Call mhlb_get_order first and send that model back with your edits,' which is concrete when-to-use guidance. It also prescribes the confirmation sequence and warns against passing confirmToken on the first call. It does not explicitly contrast with mhlb_create_order for new orders, but 'existing lunch order' plus the get_order prerequisite make the intended use clear.

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

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

Goes far beyond the sparse annotations (readOnlyHint=false, destructiveHint=false) by disclosing that the endpoint replaces the whole record so omitted fields are lost, that user confirmation is mandatory, and that the request shape is UNVERIFIED against a live account. The 'Inspect the confirmation preview before approving it' caution adds actionable risk guidance the annotations cannot convey.

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?

Four sentences, each earning its place: the one-line purpose, the round-trip workflow, the two-mode confirmation mechanics, and the unverified-status warning. The confirmation sentence is dense and the UNVERIFIED note runs slightly long, but there is no redundancy with 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?

For a mutation tool with a nested object parameter, a two-step confirmation fallback, and no output schema, the description covers preconditions, destructive replacement semantics, the confirmation protocol, and the unverified risk. The main gap is the absence of any description of the success or error response shape beyond the confirmToken mention, which the schema only partly offsets.

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 100% schema description coverage the baseline is 3, and the description earns the extra point by explaining the reasoning behind the student parameter: the whole-record replacement means the caller must send the full model back or silently lose omitted fields, which motivates the get_form-then-edit round trip. It also reinforces the confirmToken's restricted lifecycle by summarizing when the token is and is not legitimate.

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?

Opens with the specific verb-resource pair 'Update a student profile' and immediately disambiguates the semantics with 'the endpoint replaces the whole record.' The workflow reference to mhlb_get_student_form clearly separates editing an existing student from the sibling create/new-student tools without requiring schema inspection.

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 and workflow — 'Call mhlb_get_student_form first and send that model back with your edits' — and precisely describes how the confirmation flow behaves in both elicitation-capable clients and the fallback token path. It stops short of naming when-not-to-use alternatives such as mhlb_create_student or mhlb_delete_student, so exclusions are 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 and openWorldHint, and the description supplements this by listing the specific returned information: name, email, role, counts, balances, and subscription flags. It also frames the call as a session validation, adding context beyond the annotations without contradicting them.

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

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

The description is two short sentences with no filler. The data enumeration is dense but useful, and the 'Start here' guidance adds practical value without bloat.

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 zero parameters and no output schema, the description covers what the tool does, what it returns, and why to call it first. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

The tool has zero parameters, so the description has no parameter burden and the baseline 4 applies. The description's reference to 'the signed-in account' clarifies that the tool relies on the active session rather than any input.

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 says 'Get the signed-in My Hot Lunchbox account' with a specific verb and resource, then enumerates the data returned. This makes it clearly distinct from sibling transaction, student, order, and subscription tools.

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

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

The description explicitly says 'Start here to confirm the session works,' giving a clear trigger condition. It does not name alternatives, but no sibling provides the same whoami/session-check functionality, so the guidance is sufficient.

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