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

Annotations already indicate a write (readOnlyHint=false) and open world. The description adds significant context by warning that the write is UNVERIFIED and derived from a compiled API client, and instructs to inspect the dry-run preview before confirming. This is a valuable disclosure beyond annotations, though it doesn't describe exact side effects or return structure.

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 concise: one sentence states the action, and a second sentence provides a critical caution. The main purpose is front-loaded, and no unnecessary words. It is appropriately sized for the tool's complexity.

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 write nature, the presence of a confirm parameter, and no output schema, the description, combined with the schema, gives an agent enough to safely invoke the tool. The warning about unverified behavior and the instruction to inspect the preview cover important operational details. Return format is not essential here.

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

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

Schema description coverage is 100%. The schema already explains both parameters (code and confirm), including the preview behavior. The description adds minimal parameter-specific meaning beyond the note about dry-run preview, which is already in the confirm schema. So it does not substantially exceed the schema baseline.

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 ('Apply a coupon code to the account') with a clear verb and resource. It distinguishes from siblings like mhlb_apply_gift_card (different resource) and mhlb_get_coupon/remove_coupon (different actions), so an agent can correctly select it.

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 when a coupon must be applied, but does not explicitly mention alternatives or exclusions. It provides a caution about the unverified write but no direct guidance on when to prefer this over mhlb_apply_gift_card or mhlb_remove_coupon. Some context is given, but no 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 mark readOnlyHint=false and openWorldHint=true, so the write nature is known. The description goes further by explicitly warning that the request shape is UNVERIFIED and instructing to inspect the preview, adding valuable behavioral context beyond annotations without 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 compact sentences, with the core purpose in the first and a critical safety note in the second. Zero filler, all information 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 write operation with no output schema, it covers the essential aspects: what the tool does, the risk (unverified), and the recommended workflow (preview). It doesn't detail the preview format, but the description gives enough to proceed 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%, and the schema already thoroughly describes both parameters ('code' as gift card code, 'confirm' as required for actual execution). The description adds no new parameter-level meaning; it only restates the action, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Redeem'), a precise resource ('gift card code'), and the effect ('onto the account balance'). It clearly distinguishes this tool from siblings like mhlb_apply_coupon by naming the exact resource type.

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 operational guidance: inspect the dry-run preview before confirming. It does not explicitly contrast with alternatives, but the purpose clarity combined with the safety instruction provides sufficient context for correct use.

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 indicate readOnly=false and openWorldHint=true. The description goes far beyond: it warns the write is UNVERIFIED, derived from compiled client, not exercised live. It explains the expectedTotal's role as attribution-only and the need to inspect dry-run before confirming. This is exemplary transparency for a risky write operation.

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

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

The description is one dense paragraph that front-loads the purpose, then gives prerequisite, limitation, and caution. No filler; every sentence carries necessary information. It's appropriately concise for the tool's complexity.

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 9 parameters, no output schema, and a real-money write, the description covers all essential operational aspects: what it does, prerequisite, limitation, verification status, and confirmation workflow. The agent has enough to invoke it safely and 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 descriptions cover all 9 parameters, so the baseline is 3. The description adds critical context for expectedTotal—that the server prices from orderIds, so this value is recorded for attribution, not for validation—which is beyond the schema. It also reinforces the init_checkout flow. This elevates it to a 4.

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

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

The description opens with a specific verb and resource: 'PAY for the lunches in the cart.' It clearly distinguishes this from siblings like mhlb_init_checkout by stating it charges a real payment method. No ambiguity about the operation's goal.

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 instructs to run mhlb_init_checkout first, read the total, and pass it as expectedTotal. It also notes the hard limitation that only saved cards can be used, so agents know when this tool is not applicable. The dry-run preview instruction further guides when to confirm.

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, openWorldHint=true), the description discloses critical behavioral traits: the write is UNVERIFIED and its request shape was derived from compiled API client but not exercised against a live account. It also instructs to inspect the dry-run preview before confirming, which adds important safety context. The description does not contradict the annotations.

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

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

Three sentences, each carrying essential information: the primary action, the workflow prerequisite, and the critical unverified warning. The structure front-loads the purpose and efficiently folds in exclusions and cautions without redundancy. 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?

Given the tool's complexity (nested order object, confirm flag, write operation) and lack of an output schema, the description is quite complete. It covers the workflow, the dry-run preview, and the unverified risk. It slightly lacks an explicit statement of what happens on success (e.g., returns a confirmation or updates the cart), but the mention of the preview and confirm flow adequately guides the agent. A minor gap prevents a 5.

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 adequately. The description echoes the order-model workflow ('send that model back with quantities set') but does not add meaning beyond what the schema provides. It also mentions the confirm parameter's role indirectly via 'dry-run preview', but schema already explains it. Thus 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 begins with a specific verb-resource pair: 'Place a lunch order into the cart.' It clearly establishes the tool's function and differentiates it from siblings like mhlb_get_order_form (fetching the form) and mhlb_checkout (payment). The wording 'adds to the cart — it does not pay' further disambiguates it from potential payment-related 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?

Explicitly instructs to call mhlb_get_order_form first and send that model back with quantities set, establishing a clear precondition and workflow. It also states 'use mhlb_checkout for that' to direct the agent away from this tool for payment, effectively naming the alternative and the condition that selects 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?

Goes well beyond annotations by disclosing the tool is 'UNVERIFIED' and derived from a compiled client, warning to inspect the dry-run preview. It also explains the confirm parameter's gating behavior, which is critical for safe use.

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

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

Two sentences, no filler. The main action and prerequisite are front-loaded; the critical warning is separate and prominent. 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 create operation with a nested object and confirmation flag, the description covers the workflow, the preview mechanism, and the verification risk. It doesn't detail the success output, but given the dry-run emphasis and the schema, this is sufficient 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 descriptions already cover both parameters (100% coverage). The description adds value by clarifying that the 'student' object should come from the form tool and that 'confirm' triggers the actual write after a preview, enriching meaning 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 verb ('Add') and resource ('a student') with scope ('to the account'), clearly distinguishing it from update/delete/retrieve siblings. The phrasing leaves no ambiguity about the tool's role.

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?

Explicitly requires calling mhlb_new_student_form first and sending the returned model with edits, giving a clear prerequisite. Though it doesn't explicitly contrast with update/delete, the verb 'Add' and the workflow make the usage context unambiguous.

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

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

Beyond the annotations (readOnlyHint:false, openWorldHint:true), the description discloses that refund behavior is not controlled here, and crucially warns that the write is UNVERIFIED, derived from compiled API client, and advises inspecting the dry-run preview. This is exactly the kind of behavioral caution an agent needs for a destructive operation, surpassing what annotations provide.

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

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

Two sentences, zero filler. The primary action is front-loaded, followed by the refund caveat and the verification warning. Every clause earns its place; it is concise without sacrificing critical information.

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

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

Given the complexity (write op, 6 params, no output schema), the description covers the core action, the refund limitation, and the verification warning. It does not explain return values, but with no output schema that is acceptable. It could explicitly state that this is for canceling an existing order (not a subscription) but the schema's isSubscribed parameter and dry-run advice partly compensate. Otherwise, it is quite 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?

The input schema has 100% description coverage for all six parameters, so the schema already documents what each expects. The description adds a note about the dry-run preview tied to 'confirm', which is contextual but does not enrich parameter semantics beyond the schema. 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 clear, specific verb-resource pair: 'Cancel a lunch order.' This immediately distinguishes it from siblings like mhlb_unsubscribe_order (which targets subscriptions) and mhlb_update_order (modification). No ambiguity about what action is performed.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention mhlb_unsubscribe_order for recurring orders or differentiate from mhlb_update_order. The only hint is buried in the schema's isSubscribed param, but the description itself omits any 'when-to-use' direction.

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 critical behavioral disclosure beyond annotations: irreversibility, data loss (order history), and the fact that it is unverified and derived from compiled API client. It also instructs the user to inspect the dry-run preview, which is valuable transparency that annotations do not cover. No contradiction with annotations (readOnlyHint=false aligns with write operation).

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 concise and well-structured: action first, then consequences, then a crucial warning. Every sentence adds value, and the note is prominent without being verbose.

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 delete operation, the description covers the key aspects: irreversibility, data loss, verification status, and dry-run mechanism. The schema provides parameter details, and no output schema is needed for a delete. It is complete 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 coverage is 100% with clear descriptions for both parameters (studentId from mhlb_list_students, confirm as a boolean gate). The description adds no additional parameter semantics beyond the schema, so it meets the baseline for high 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 clearly states the action ('Remove a student') and the resource, distinguishing it from update or create operations. It also specifies the consequence (order history removed), leaving no ambiguity about what this 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 implies when to use (when permanent removal is desired) but does not explicitly compare to alternatives like update_student or mention conditions for not using. It provides context about irreversibility but lacks explicit 'when not to use' guidance given the sibling set.

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 value by detailing the granularity ('per student') and the set of statuses returned, which is behavioral context beyond the annotations. It does not mention pagination or response shape, but the read-only nature plus enumerated statuses is sufficient given the annotation coverage.

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

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

The description is two sentences with no filler. The primary action and scope are front-loaded, followed by a concise enumeration of what the calendar includes. 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 read-only date-range query with two well-documented parameters, the description conveys the high-level return content (statuses per student) but does not detail the exact response structure (e.g., grouping, ordering). Since there is no output schema, this is a minor gap, but not critical for an agent to successfully invoke the tool.

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

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

The input schema already provides full descriptive coverage (100%) for both startDate and endDate, each with a clear format hint and meaning. The description does not add any additional parameter-specific semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Get'), the resource ('lunch calendar for the account'), and the scope ('over a date range'), then enumerates the specific statuses returned (open, ordered, paid, in cart, subscribed, closed) per student. It also explicitly ties it to the Lunch Calendar page, distinguishing it from related tools like mhlb_get_day or mhlb_get_cart.

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 context on what the tool returns, implying it is the definitive source for per-day ordering status across a range. While it does not explicitly name alternatives or state 'when not to use', the reference to the Lunch Calendar page provides enough contextual signal for an agent to infer its role among siblings such as mhlb_print_calendar or mhlb_get_day.

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's 'Get' aligns and does not need to repeat safety. The description adds useful context that the cart contains lunches not yet paid for, which clarifies scope. It does not disclose return format, pagination, or any operational nuances beyond that, but with annotations covering safety, the description adds moderate value without 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?

The description is a single, tight sentence that leads with the core purpose, immediately defines the resource, and then lists filter options. Every clause earns its place—no filler, no redundancy. It front-loads the most important information (what the cart is) before optional filters.

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 three optional parameters and no output schema, the description gives a clear purpose and filter options. It omits mention that period and orderStatus values should be sourced from mhlb_get_cart_tabs, but the schema already specifies that, so the agent can discover it. It also doesn't describe the response shape, but without an output schema that might be acceptable. The openWorldHint suggests richer data but isn't elaborated; overall, the description is adequate for correct invocation, with minor gaps like inter-tool dependencies.

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% — each parameter (period, studentId, orderStatus) has its own description. The tool description merely paraphrases filtering ('Filter by order status and ordering period, or narrow to one student') without adding new semantic details like value formats or allowed sources beyond what schema already provides (e.g., orderStatus is tied to mhlb_get_cart_tabs in the schema). Since the schema carries the parameter meaning, the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Get' and a clearly defined resource: 'the shopping cart — lunches added but not yet paid for.' This distinguishes it from related siblings like mhlb_get_cart_tabs (which returns tab values), mhlb_get_order (which likely deals with placed orders), and transactional tools. The definition of what constitutes the cart is precise 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 explains what the tool returns (lunches not yet paid for) and states it can be filtered by order status and ordering period or narrowed to a student. While it doesn't explicitly name alternatives, the phrase 'not yet paid for' implies contrast with paid/placed orders, giving contextual guidance. It does not, however, explicitly say when to prefer this over mhlb_get_order or mention that filter values come from mhlb_get_cart_tabs (that is only in the schema).

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 include readOnlyHint=true, so no side-effect disclosure is needed. The description adds value by explaining what the tool returns (valid filter values, default selection) and that it is a prerequisite. It does not contradict annotations. It could elaborate on how the values are presented, but given the readOnlyHint, it is adequately 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, well-structured sentence that front-loads the purpose and immediately states the usage instruction. Every word contributes meaning; there is no redundancy or filler. It is concise and efficient.

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 helper with no output schema, the description covers key aspects: what it returns, its relationship to mhlb_get_cart, and when to invoke it. It doesn't specify the exact output format, but the agent can reasonably infer it from the context. Given the tool's low complexity and the presence of annotations, it is sufficiently 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?

The input schema already provides 100% description coverage for all three parameters. The description adds contextual meaning by linking 'period' to ordering periods (semesters) and 'tabName' to status tabs, but this mostly mirrors the schema. Since schema coverage is high, the description doesn't need to compensate; it doesn't add significant semantic depth beyond what the schema states.

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

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

The description clearly states the tool's function: retrieving valid filter values (ordering periods and status tabs) for mhlb_get_cart, including which is selected by default. It names the target resource (mhlb_get_cart) and distinguishes itself as a prerequisite helper. The verb 'Get' is explicit and the scope is 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 explicitly instructs 'Call this before filtering the cart,' giving a clear usage directive. It does not mention when not to use it or alternatives, but for a helper tool tightly coupled to mhlb_get_cart, this is sufficient. The context is clear enough for an agent to know it's a preparatory step.

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 the possibility of a null/empty result. The description adds the detail that the coupon is 'currently applied to the account' and includes 'if any', which aligns with openWorldHint but doesn't introduce new behavioral context (e.g., auth requirements, rate limits, or response format). Since annotations carry most of the burden here and the description adds minimal extra value, a 3 is appropriate.

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

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

The description is a single, efficient sentence that leads with the action and resource, and includes the qualifier 'if any' to set expectations. There is no filler or redundancy; every word contributes to the meaning, making it appropriately concise and well-structured.

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

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

For a zero-parameter read tool with openWorldHint and readOnlyHint annotations, the description is nearly complete. It states what the tool does and hints at the possible empty result via 'if any'. The absence of an output schema means the exact return shape is not specified, but given the simplicity and the annotations, the description is sufficient for an agent to invoke the tool correctly. A 5 would require explicit mention of the return structure or edge cases, but this is adequate given the 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?

The tool has zero parameters, so the baseline is 4 per the rubric. There is nothing for the description to clarify about parameters, and the schema (which is empty) provides no further information. The description adds no parameter-related details because none are needed.

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 specific resource ('the coupon currently applied to the account'). It clearly distinguishes this from sibling tools like mhlb_apply_coupon and mhlb_remove_coupon by focusing on reading the current state. The phrasing 'if any' also clarifies the possibility of no coupon being applied, leaving no ambiguity about the tool's 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?

The description does not explicitly mention when to use this tool versus alternatives like mhlb_apply_coupon or mhlb_remove_coupon. However, the getter nature is implied by the name and the readOnlyHint annotation, and the sibling list makes the read-vs-mutate distinction obvious. It provides clear context that this is for inspecting the current coupon, but it stops short of explicitly guiding the agent on when to call it instead of others, which would merit a 4.

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, indicating a safe, read-only operation with potentially non-enumerable results. The description does not contradict these annotations and adds a small amount of context by specifying the returned fields (items, sizes, quantities, etc.), but it does not disclose additional behavioral traits such as handling of missing dates, response format, or limits. Given the annotation coverage, a baseline 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, well-crafted sentence that front-loads the core action and resource, then immediately specifies the returned details. There is no filler or repetition. Every part of the sentence contributes to the agent's understanding. It is efficient and appropriately sized for the tool's simplicity.

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 query tool with two parameters, a full schema, and annotations covering safety, the description provides sufficient context by enumerating the returned data fields. It does not mention edge cases like 'no order on that date' or whether the result is a single object or list, but given the openWorldHint and typical usage, these are minor omissions. The description is reasonably complete for an agent 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?

Schema description coverage is 100%, so both parameters (studentId and date) are already documented in the schema with descriptions. The tool description adds no extra semantic information about the parameters—it only implies a date-based query. With full schema coverage, the description does not need to compensate, so the baseline 3 is accurate.

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 verb 'Get' and the resource 'what a student has ordered on one specific date', and enumerates the returned details (items, sizes, quantities, add-ons, prices). It is specific and unambiguous, though it does not explicitly differentiate from sibling tools like mhlb_get_order or mhlb_get_cart. However, the scope (a specific date) is a distinguishing feature, so it is clear enough for an agent.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or situations where this tool is preferred over mhlb_get_order or other retrieval tools. An agent would have to infer usage solely from the resource name and schema, which is insufficient for nuanced decisions.

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 read-only nature is structured. The description adds the context that it is the 'read half' of placing an order, which hints at a typical workflow but does not disclose additional behavioral traits like response format, pagination, or error handling. Since annotations carry the safety profile, the description adds modest value, earning a 3.

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 redundancy. The first sentence states the action, scope, and content list; the second provides a contextual hook. Information is front-loaded and every word earns its place. Excellent structure for an agent to parse quickly.

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

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

For a simple read-only tool with two straightforward parameters and no output schema, the description is fully complete. It enumerates the expected return fields (vendor, items, sizes, add-ons, prices, ordering deadline) and clarifies the single-student single-date scope. An agent can invoke the tool correctly without needing additional 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?

The input schema documentation covers 100% of parameters (both date and studentId are described with formats and provenance). The description does not add any semantics beyond the schema—it does not elaborate on date validation or studentId usage. Per the baseline for full schema coverage, this scores 3.

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

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

The description uses a specific verb ('Get') and resource ('orderable menu') with precise scope ('one student on one date'). It lists the contents (vendor, items, sizes, add-ons, prices, ordering deadline), clearly distinguishing it from sibling tools like mhlb_get_cart or mhlb_get_order_form. This is not a tautology and leaves no ambiguity about the tool's function.

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' provides clear context that this tool should be used as a precondition to placing an order. It does not explicitly name alternatives (e.g., mhlb_get_order_form) or state exclusions, but the context is sufficient for an agent to infer when to use it. No misleading guidance is present.

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

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

The readOnlyHint annotation already signals this is a safe read operation. The description adds the key behavioral detail that the returned data is specifically formatted for editing, which is useful context beyond the annotation. It also subtly hints at a workflow relationship with update. 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?

The description is a single, well-structured sentence that gets straight to the point. It front-loads the core purpose and adds a meaningful contextual note about the update tool. 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 is a simple read operation with readOnlyHint true and all parameters optional and documented, the description provides sufficient context for an agent to understand its role. The 'editable form' detail is important and covered. It might have noted the required parameter combinations, but the schema handles that. Overall, adequate.

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 (eventId, orderId, studentId) already have clear descriptions in the schema. The tool description does not add any additional parameter semantics, which is acceptable given the schema already 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 action ('Get an existing order') and adds an important qualifier ('in editable form') that distinguishes it from other get tools like mhlb_get_cart or mhlb_get_order_form. It also clarifies the purpose by noting it feeds into mhlb_update_order. This effectively differentiates it from siblings.

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

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

The description implies the tool is a prerequisite for mhlb_update_order, giving clear context for when to use it. However, it does not explicitly state when not to use alternatives like mhlb_get_order_form or mhlb_get_cart. There is a clear implied usage but no explicit exclusions, so slightly less than perfect.

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 annotation readOnlyHint=true already signals a safe read operation. The description adds value by disclosing that the returned model is the exact structure expected by mhlb_create_order and is pre-populated with available items. This provides actionable behavioral 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?

A single, well-structured sentence that front-loads the core purpose and then clarifies the return value with a dash. There is zero redundancy; 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?

Since there is no output schema, the description adequately explains the return value (blank order model pre-populated with available items) and its intended use. Combined with annotations covering safety and schema covering parameters, nothing essential is missing for an agent to call this 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?

Both parameters are fully documented in the schema (100% coverage) with references to source tools (mhlb_get_menu/mhlb_get_calendar for eventId, mhlb_list_students for studentId). The description itself adds no additional parameter semantics, 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'), a specific resource ('blank order model'), and the context ('for a student on a specific lunch event'). It also explicitly connects to mhlb_create_order, which distinguishes it from mhlb_get_order and other siblings. The purpose is 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 implies this tool is used before creating an order by stating it provides the exact structure that mhlb_create_order expects. It names the create tool and describes the pre-populated items. However, it does not explicitly state when NOT to use it (e.g., for retrieving an existing order via mhlb_get_order), so the guidance is strong but not fully 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, so the description need not restate read-only behavior. It adds useful context that the return value is structured as the update model, and describes the form fields, but does not disclose additional behaviors such as error handling or access requirements. Given the annotations cover the safety profile, a 3 is appropriate.

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

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

Two sentences with no wasted words. The primary purpose is stated first, followed by the critical link to the update tool. Every clause 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?

For a single-parameter, read-only getter with no output schema, the description is sufficiently informative. It lists the fields returned, mentions dropdown options, and explicitly ties the response shape to update_student, which is essential for correct subsequent calls. No critical missing information 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?

The input schema has 100% coverage with a clear description of studentId as 'Student id from mhlb_list_students' and proper constraints. The tool description adds no additional meaning beyond what the schema already 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?

Clearly states the verb 'get', the resource 'editable profile for one student', and enumerates the fields it returns (school, grade, teacher, delivery location, allergies, dropdown options). This distinguishes it from siblings like get_order and list_students without ambiguity.

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?

Implicitly indicates when to use this tool by noting it returns the exact model that mhlb_update_student expects back, linking it to an edit workflow. It does not explicitly state when not to use it, but the context is sufficient for an agent to infer it should precede update operations.

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 and non-exhaustive nature. The description adds value by stating exactly what the returned configuration contains ('whether recurring ordering is on, and its terms'), providing concrete output expectations beyond the annotation flags. This is useful for an agent deciding whether the tool meets its needs.

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, tightly worded sentence that front-loads the main purpose and then specifies the two key components. There is no fluff, redundant phrasing, or unnecessary detail. It efficiently conveys all needed information in minimal text.

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, no nested objects), the description fully covers what an agent needs to know to call it correctly: it retrieves account-level subscription configuration and indicates the kind of data returned. The annotations cover safety and openness, so nothing is missing for correct invocation.

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

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

The tool has zero parameters and the schema is an empty object, so the description cannot add parameter-specific details. Per the baseline for 0 parameters, a score of 4 is appropriate because the description does not need to compensate for missing schema information and it already clarifies the tool's output focus, which is relevant to understanding the call.

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

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

The description clearly identifies the tool as retrieving the account's subscription configuration, specifying exactly what it covers (recurring ordering status and terms). This distinguishes it from siblings like mhlb_list_subscriptions (which likely list individual subscriptions) and mhlb_set_subscription_enabled (which modifies settings). The verb 'Get' and resource 'account's subscription configuration' form a specific, 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?

While the description implies this is for reading account-level subscription settings, it does not explicitly contrast it with related siblings such as mhlb_list_subscriptions or mhlb_set_subscription_enabled. There is no 'use this when...' or 'instead of...' guidance, so an agent must infer the appropriate context from the tool name and sibling list. This leaves room for confusion.

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 nature is known. The description adds context about what kind of detail is returned ('line-item detail' and 'which lunches it paid for'), which is useful. However, it doesn't disclose any additional behavioral traits like authentication requirements, rate limits, or side effects. With annotations covering the safety profile, this is adequate but not rich – a score of 3 reflects that the description adds some value beyond annotations but not extensive behavioral 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 a single, efficient sentence with a dash for clarification. It front-loads the core action and adds a concise qualifier. There is zero redundancy, and every word adds meaning. This is an excellent example of concise and well-structured text.

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

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

For a simple one-parameter, read-only tool with no output schema, the description gives sufficient context: it tells what the tool retrieves and even hints at the content ('line-item detail' and 'which lunches it paid for'). It does not describe pagination, return format, or error handling, but these are likely not critical for a get-by-id operation. The description is complete enough for an agent to know when to call it and what to expect, though more detail on the response structure could push it to a 5.

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 for the single parameter transactionId is 100%, and the schema description already explains it as the id field from mhlb_list_transactions. The tool description does not add any further meaning about the parameter. Since the schema is comprehensive, the baseline of 3 is appropriate – the description doesn't need to compensate for parameter explanation.

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'), a resource ('transaction'), and adds specificity with 'line-item detail' and 'which lunches it paid for.' This distinguishes it from sibling tools like mhlb_list_transactions (which lists transactions) and mhlb_get_order (which handles orders). The purpose is immediately understandable 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 does not provide explicit guidance on when to use this tool versus alternatives. It implies that you'd use it to retrieve details for a single transaction, but it doesn't mention mhlb_list_transactions or any exclusion criteria. The schema's parameter description hints at a workflow (get the id from list), but the tool description itself lacks usage direction. There are no when-to-use or when-not-to-use instructions.

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 readOnlyHint=true and idempotentHint=true annotations, the description adds that it never returns the credential, performs exactly one authenticated request, diagnoses three distinct failure categories, and reports credential source and round-trip time. This is rich, honest behavioral disclosure with no contradiction to 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 compact yet information-dense. Every sentence contributes: what the tool does, what it reports, what it never returns, and when to use it. The 'Read-only' safety note is placed early, and the usage trigger closes the description cleanly.

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

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

For a zero-parameter, read-only diagnostic tool without an output schema, the description fully covers inputs, behavior, safety, output semantics, and the intended failure scenario. Nothing an agent needs to decide when to call it or interpret its result is missing.

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

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

There are zero parameters, and the schema description coverage is 100% by default. The description correctly focuses on behavior rather than parameters. Baseline 4 applies because there is nothing parameter-related to explain.

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

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

The description states the exact action ('resolves the credential', 'makes one authenticated request'), the target upstream, and what it reports. This clearly distinguishes mhlb_healthcheck from sibling tools like mhlb_whoami, which likely checks identity locally rather than upstream reachability.

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 an explicit trigger: 'Call this when a real tool fails and you want to know which hop broke.' It does not enumerate alternatives or when-not-to-use conditions, but the stated use case is specific and actionable.

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

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

Annotations indicate readOnlyHint=false and openWorldHint=true. The description adds critical behavioral detail: it is a non-charging read step, but the confirm flag implies potential side effects beyond pure read (e.g., creating a checkout session). It also discloses that the request shape is unverified and advises inspecting the dry-run preview. This adds transparency beyond what annotations provide, though it could have been more explicit about whether confirm triggers any state 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 compact: three sentences that front-load the main purpose and return values, followed by a crucial unverified warning. It avoids redundancy and keeps the critical caveat near the end without diluting the core message. Minor excess: 'as mhlb_init_checkout reports it' for checkoutType is a bit circular, but overall efficient.

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 checkout-init tool with no output schema, the description adequately covers purpose, usage sequence, and safety warnings. It references related tools for parameter sources and clarifies the confirm behavior. The main gap is potential side effects of confirm=true (does it create a session or just return preview?), but that is partially covered by the unverified warning. Overall complete for confident 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%, giving a baseline of 3. The description adds cross-references (e.g., orderIds 'from mhlb_get_cart', checkoutType 'as mhlb_init_checkout reports it', schoolDonations 'as returned by mhlb_init_checkout') that tie parameters to their source or expected format. It also clarifies confirm's role. These enrich the schema, justifying a 4.

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

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

The description states a specific verb ('Start checkout') and resource ('the cart'), and details what it returns (order summary, totals, taxes, applied credits, payment methods). It also distinguishes itself from mhlb_checkout by labeling itself as the read step before the charging action, making it clearly differentiated from 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?

Explicitly states when to use it ('the read step before mhlb_checkout') and clarifies what it does not do ('does NOT charge anything'). It also instructs on the confirm flag: without true, returns a preview, with true proceeds. This gives clear operational guidance and anticipates the checkout sequence.

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 specific return fields (codes, balances, status), which is useful context beyond annotations, but does not describe pagination, filtering, or failure behavior. This modest addition justifies a 3.

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

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

One short, front-loaded sentence with no wasted words. It communicates both the action and the key output details efficiently.

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, parameterless list tool with readOnly and openWorld annotations, the description provides the essential output fields. Though there is no output schema, the description covers the core information an agent needs to use the result correctly. Minor gaps like pagination are not critical here.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Per rubric, a baseline of 4 is appropriate since there is nothing to explain; the description correctly implies no inputs are needed.

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 ('List'), resource ('gift cards'), and scope ('on the account'), and details the returned content (codes, balances, status). Clearly distinguishes from siblings like mhlb_apply_gift_card or mhlb_get_transaction by indicating a read-only enumeration of 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?

No explicit when-to-use guidance or mention of alternatives. While the purpose is obvious for a simple list operation, the description does not compare with other list tools (e.g., mhlb_list_subscriptions) or note conditions for using this vs. them.

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 restate safety. It adds useful output-scope details (orders status, inactive profile, unaccepted invites) and emphasizes the id's role, which is mildly behavioral. However, it does not disclose any edge conditions, pagination, or error behavior, so it stays at a baseline level.

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, tightly worded sentence delivers the purpose, output fields, and a note on the id's cross-tool importance. No fluff, no redundancy, and front-loaded with the action and target.

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

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

With no parameters and no output schema, the description fully specifies what the agent will receive (specific fields and statuses). It explains why the output matters (id feeds other tools). Nothing critical is missing for a simple list operation.

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 per the rubric the baseline is 4. The description correctly omits parameter details because none exist; nothing more is needed.

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 ('List') and resource ('students on the account') and enumerates the exact fields returned (id, first name, school, grade/teacher, orders status, profile status). This clearly distinguishes it from sibling tools like mhlb_create_student or mhlb_get_student_form, which are different actions on students.

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 notes that 'The student id feeds every calendar and ordering tool,' which gives clear motivation for when to invoke this tool (to obtain student IDs for downstream operations). It doesn't explicitly state when not to use it or name alternatives, but since it is the sole tool for listing students, the usage context is adequately implied.

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

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

The annotations already declare readOnlyHint=true, so the description does not need to restate that. It does add the 'upcoming' scoping and explains that these are recurring automated orders, which is useful context. However, it does not disclose details like pagination, sorting, or what happens when no period is supplied, so it adds only partial 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?

The description is a single sentence that leads with the action and resource, then clarifies the concept. It contains no redundant wording and is immediately understandable.

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 list tool with one optional parameter, the description adequately conveys the purpose. However, it does not specify the return format or any default behavior when period is omitted, and there is no output schema to fill that gap. Given the low complexity, this is mostly sufficient but not fully exhaustive.

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

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

The schema already provides a 100% description for the 'period' parameter ('Ordering period to scope to'). The tool description does not add any additional meaning or usage details for this parameter, so it relies entirely on the schema.

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

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

The description states a specific verb ('List') on a specific resource ('upcoming lunch subscriptions') and clarifies the meaning by calling them 'recurring orders that will be placed and charged automatically.' This clearly distinguishes it from other list tools like mhlb_list_transactions and mhlb_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 provides no explicit guidance on when to use this tool versus alternatives such as mhlb_get_subscription_settings or mhlb_unsubscribe_order. There is no mention of conditions, exclusions, or prerequisites, leaving the agent to infer the appropriate 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?

The annotations already provide readOnlyHint=true and openWorldHint=true, indicating a safe read operation with potentially varying fields. The description adds value by specifying the output fields (date, amount, what was paid for), but it does not disclose other behavioral traits like pagination, sorting, or the effect of omitting the optional parameters (period and studentId). Given the annotation coverage, the description adds some but not rich 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 a single, efficient sentence, front-loading the action and listing the output fields. It avoids fluff and is easy to parse, though it could benefit from including usage guidance or parameter context. It is not verbose, so it earns a 4 rather than a 5 because it is slightly under-specified for a tool with optional filters.

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 list operation with two optional parameters and no output schema, the description is minimal. It states the basic function and returned fields, but does not explain when to use it, how the parameters affect results, or whether there are pagination/ordering constraints. The schema covers parameter definitions, but the description lacks sufficient guidance to ensure correct invocation in varied contexts. This is adequate but with clear gaps.

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

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

Schema coverage is 100%, with parameters 'period' and 'studentId' clearly described (e.g., period scopes to an ordering period from mhlb_get_cart_tabs, studentId limits to one student). The description does not add any additional meaning about these parameters. Per the rubric, with high schema coverage, a 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 clear verb ('List') and resource ('payment transactions'), and specifies the included fields (date, amount, what was paid for). It distinguishes from the single-transaction mhlb_get_transaction and print mhlb_print_transaction, though it does not explicitly mention those alternatives. The phrase 'on the account' implies a broad scope, which is understandable given the sibling names.

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

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

No guidance is provided on when to use this tool versus mhlb_get_transaction, mhlb_print_transaction, or mhlb_list_subscriptions. The description only states what it does, with no mention of typical use cases, prerequisites, or conditions under which an alternative might be preferred. An agent would need to infer from the name and 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=true, so the description does not need to restate safety. It adds value by describing what the tool returns (a blank profile and school/grade/teacher dropdowns) and its role as a preparatory step for creation. This goes beyond the annotation and gives the agent a concrete expectation of the output, albeit without detailed structure.

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, tightly-worded sentence that front-loads the primary action ('Get a blank student profile'), then adds the specific dropdown options, and closes with the intended workflow. No filler, every clause 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 zero-parameter, read-only tool with no output schema, the description gives sufficient context: what is returned, what the purpose is, and how to use it next. There is no missing information an agent would need to invoke it correctly in the context of creating a new student.

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

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

The input schema has zero parameters, so there is nothing to document. Per the calibration, a baseline of 4 applies. The description does not need to add parameter details, and it does not—keeping the description clean.

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 verb ('Get') and a specific resource ('blank student profile') plus the dropdown options, and explicitly links to its intended downstream use ('pass to mhlb_create_student'). It is easily distinguished from siblings like mhlb_get_student_form (which likely fetches an existing form) and mhlb_create_student, making the purpose 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 explicitly instructs when to use the tool: to obtain a form to be filled and passed to mhlb_create_student. It does not explicitly state exclusions or alternatives (e.g., 'use mhlb_get_student_form for existing students'), but the 'new student' wording and the pointer to create_student implicitly signal the correct workflow. Clear context without explicit contrasts.

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 goes beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing that the tool writes a PDF to disk and can optionally return bytes inline. This is a meaningful behavioral detail (side effect of file creation) that the annotations alone do not convey. The description does not state file overwrite behavior or output path details, but the core side effect is transparent. 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?

The description is two sentences with no fluff: the first sentence states the primary purpose, the second explains the output modes. It is front-loaded with the core action and immediately clarifies key behavior. Every clause earns its place, making it highly efficient.

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 moderate complexity (5 parameters, no output schema), the description covers the essential return behavior (path or bytes) and the main purpose. It does not mention error conditions like invalid date ranges or the requirement for at least one student, but the latter is covered in the schema. The openWorldHint suggests external side effects, and the file-writing detail is beneficial. Overall, the description is mostly complete, though a note on parameter dependencies or typical failure modes could push it higher.

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?

Since the input schema already documents all five parameters with 100% coverage (including startDate/endDate ranges, studentIds requirement, inline boolean, filename default), the description adds little beyond what the schema provides. The mention of 'bytes inline' mirrors the inline parameter description. The baseline of 3 is appropriate because the schema carries the semantic load and the description does not add extra meaning.

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

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

The description clearly states the action ('Generate the printable lunch calendar PDF') and the scope ('for a date range'), leaving no ambiguity about the resource and operation. It also mentions the two delivery modes (disk path or inline bytes), which further clarifies what the tool produces. This distinguishes it from siblings like mhlb_get_calendar, which likely returns data rather than a printable artifact.

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 (producing a printable calendar) but does not explicitly compare against alternatives or state when not to use it. There is no mention of mhlb_get_calendar or other print tools, nor any exclusions or prerequisites. The only contextual hint is in the studentIds parameter description ('from mhlb_list_students'), which is outside the tool description. Thus the agent gets some implied guidance but no explicit 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?

Annotations only provide readOnlyHint=false and openWorldHint=true, leaving the description to carry behavioral disclosure. The description adds valuable failure behavior: it states the endpoint fails on empty studentIds and when no order matches the date/status. It also implies file-writing via the filename parameter but does not explicitly confirm side effects beyond generating a PDF. This is strong for a mutation tool and exceeds the minimal disclosure, though it omits details like response format or async behavior.

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

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

The description is two concise sentences. The first front-loads the core purpose and scope, and the second adds critical constraints and input sourcing. There is zero redundancy — every clause earns its place, and the structure is easy for an agent to parse quickly.

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

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

For a tool with 5 parameters all documented in the schema, the description covers the key operational details: single-date scope, required studentIds, failure modes, and where to get inputs. The absence of an output schema is partially mitigated by the inline parameter, which hints at the output format. It could explicitly mention the return value (file path vs base64) but the schema's inline description covers that, so completeness is high.

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 each parameter has a description, giving a baseline of 3. The tool description adds meaningful value beyond the schema by warning that an empty studentIds list causes failure (schema only states minItems:1) and by pointing to mhlb_get_calendar as the source for both date and studentIds. This directly aids correct invocation, so a 4 is warranted.

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 ('Generate') and resource ('printable order-details PDF'), scoped to a single lunch date. It explicitly distinguishes itself from range-based operations ('one date, not a range'), which differentiates it from sibling print tools like mhlb_print_calendar. This leaves 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 gives practical usage context by instructing the agent to obtain the required date and studentIds from mhlb_get_calendar, which helps sequence calls. It also highlights failure conditions (empty studentIds, no matching order) that guide when to avoid calling. However, it does not explicitly name alternatives or contrast with sibling tools like mhlb_print_transaction, so it stops short of full routing guidance.

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

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

Annotations already set readOnlyHint=false and openWorldHint=true, indicating possible side effects. The description adds useful context that the endpoint renders the passed record rather than performing a lookup, but it does not explicitly disclose the default file-writing behavior (though the inline parameter description covers it). This is acceptable given annotations shoulder the side-effect burden.

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 concise sentences with the primary purpose first, followed by a crucial behavioral nuance. Every word adds value, and there is no redundancy or filler.

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

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

The description captures the core purpose, the source of the transaction object, and the non-lookup behavior. It does not explicitly state the default file-writing side effect or the exact return format when inline is false, but these are covered in the parameter schema. Given no output schema and moderate complexity, this is adequate and largely complete.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description reinforces that the transaction object should come from mhlb_get_transaction, which matches the schema but does not add new meaning beyond that. No additional parameter semantics are introduced by the description itself.

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 verb+resource: 'Generate the printable receipt PDF for one transaction.' It distinguishes from sibling print tools by naming the resource (transaction) and clarifies that it renders an existing record rather than looking one up by id, which sets it apart from mhlb_get_transaction-like 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 instructs to 'Pass the transaction object from mhlb_get_transaction' and notes that it does not look up by id, giving a clear prerequisite and preventing misuse. However, it does not explicitly name sibling print tools (e.g., mhlb_print_calendar, mhlb_print_orders) or state when not to use those, so the guidance is strong but not fully 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?

The description discloses that this is a write operation (opposite of readOnlyHint=false), states it's UNVERIFIED, and instructs to inspect the dry-run preview before confirming. This is crucial risk information beyond what annotations provide (readOnlyHint=false, openWorldHint=true).

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, each earning its place: the action is front-loaded, and the cautionary note about verification and preview is concise. No 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?

For a simple tool with one boolean parameter and no output schema, the description covers purpose, risk, and the preview mechanism. Nothing critical is missing 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?

The schema fully describes the 'confirm' parameter with its behavior (must be true to proceed, otherwise preview). The tool description doesn't add additional parameter meaning beyond what's in the schema, so baseline 3 applies given 100% 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 clearly states the action ('Remove the coupon') and the resource ('currently applied to the account'). It distinguishes from siblings like apply_coupon and get_coupon by focusing on removal of the existing 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 implies when to use it (when a coupon is applied and needs removal) but doesn't explicitly name alternatives or give when-not conditions. The 'currently applied' qualifier helps, but it doesn't mention the sibling tools directly.

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 note the tool is not read-only and is idempotent. The description adds the mechanism (discarding the token) and the behavioral effect (subsequent call re-authenticates), which goes beyond the annotation hints. A small gap: it does not mention any impact on in-flight calls, but for a reset action this is sufficient.

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 consists of two concise sentences. The first states the action, the second gives usage context. Every word contributes to clarity, and the description is front-loaded with the primary purpose.

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

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

For a zero-argument utility tool with annotations covering idempotency and non-read-only behavior, the description fully explains its role and when to invoke it. No output schema is needed since it is a side-effect operation, and the purpose and trigger conditions are completely specified.

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 zero parameters and 100% schema coverage, the description correctly omits parameter details. No additional parameter explanation is needed because there are none; the baseline for a parameterless tool is 4, which 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 clearly states a specific action (discarding the cached access token) and its consequence (next call signs in again). It is easily distinguished from the sibling data-operation tools, as it manages session state rather than business data.

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

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

Explicitly provides two concrete trigger conditions: after changing credentials, or when calls fail with stale-session errors. This is precise guidance that leaves no ambiguity about when the tool should be used.

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

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

The description explicitly warns that the write is UNVERIFIED and derived from a compiled API client, instructs the agent to inspect the dry-run preview before confirming. It also discloses the behavioral consequence of enabling (future lunches ordered and charged automatically). This goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) and adds critical safety context.

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

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

Two sentences with no filler. The purpose is stated first, followed by the critical safety warning. 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 a mutation with no output schema, but the description covers the safety-critical aspects (unverified, dry-run guidance) and the behavioral effect. It does not describe what the preview returns or any response format, but given the openWorldHint and simple boolean parameters, this is adequate. An agent has enough to invoke it correctly, especially with the confirm safeguard in the 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 both parameters (confirm, enabled) are already described in the schema. The description adds value by explaining the real-world impact of enabled=true ('future lunches are ordered and charged automatically'), which is not in the schema, and it reinforces the confirm parameter's role via the dry-run instruction.

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 ('Turn on or off') and resource ('recurring lunch subscriptions'), and explains the consequence of ON ('future lunches are ordered and charged automatically'). This clearly differentiates it from siblings like list_subscriptions or get_subscription_settings.

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—when you need to toggle recurring subscriptions—but does not explicitly mention alternatives or when not to use it. Sibling tools such as mhlb_get_subscription_settings or mhlb_unsubscribe_order are not referenced, leaving the distinction 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?

The description is exceptionally transparent about the write's unverified nature ('UNVERIFIED — its request shape was derived... has not been exercised against a live account') and advises a safe workflow via the dry-run preview. This goes far beyond the annotations (readOnlyHint=false, openWorldHint=true) and provides critical risk context. No contradiction with annotations; in fact, it reinforces the openWorldHint.

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 fluff. The action is stated first, followed by a vital safety warning. Every word earns its place, making it highly efficient for an agent to parse quickly.

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

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

For a tool with a destructive write operation, the description covers the essential context: what it does, the unverified risk, and the preview mechanism. The schema handles parameter details and there is no output schema to explain. It lacks an explicit note on when to prefer this over mhlb_delete_order, but given the schema's mention of default values, the context is largely 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?

With 100% schema description coverage, every parameter already has a clear description in the schema, including the confirm behavior and the isSubscribed default distinction. The description itself adds no parameter-level semantics; the baseline of 3 is appropriate since the schema carries the full burden.

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

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

The description clearly states the action ('Stop a recurring subscription') and the resource ('a specific lunch order'), making its intent obvious. However, it does not explicitly distinguish itself from the sibling mhlb_delete_order, although the schema's description of the isSubscribed parameter hints at the distinction. The core purpose is clear enough for an agent to understand what this 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 includes a crucial usage instruction: 'Inspect the dry-run preview before confirming,' which guides the agent to verify before executing. However, it does not provide explicit guidance on when to use this tool over alternatives like mhlb_delete_order or mhlb_set_subscription_enabled. It implies the tool is for recurring subscriptions but does not state exclusions or alternatives.

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

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

The description discloses that the write is UNVERIFIED and derived from a compiled API client rather than tested against a live account — a critical caveat for an agent deciding whether to trust the operation. It also reveals the endpoint replaces the entire order (not a patch) and that confirm=false yields a preview. These go well beyond the sparse annotations (readOnlyHint: false, openWorldHint: true) and align with them, adding significant 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?

Three sentences, each earning its place: the action and replacement model, the mandatory pre-call for the model, and the critical unverified warning. The most operationally important fact (replacement vs. patch) is front-loaded. No redundant phrasing or repetition of schema fields.

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

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

The description fully explains the end-to-end flow: retrieving the model, editing, previewing, confirming. The absence of an output schema is mitigated by the explicit mention of the dry-run preview. It does not describe post-confirmation return values or error states, but given the unverified disclaimer and the preview gate, an agent has enough to safely call it. A 4 is appropriate; a 5 would require a bit more about what happens after confirm.

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 already documents both parameters with accurate descriptions (order model from get_order/get_order_form; confirm boolean). The description adds value by explicitly instructing to 'send that model back' with edits, making the round-trip pattern clear and explaining that the order parameter must be the full returned object, not a partial. Schemas cover 100%, but the description enriches the meaning beyond the property 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 opens with 'Change an existing lunch order', a specific verb and resource that immediately distinguishes it from mhlb_create_order and mhlb_delete_order by the word 'existing'. It also states the replacement semantics ('replaces the whole order') which clarifies the scope. No ambiguity remains 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 gives an explicit workflow: call mhlb_get_order first, send that model back with edits, and confirm only after inspecting the dry-run preview. It names the prerequisite sibling tool and the required confirm step, leaving no room for missue. It also implies the when-not-to-use by requiring an existing order, which no other sibling covers this directly.

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 openWorldHint=true, but the description adds critical behavioral context: the operation is a write, it replaces the entire record (omitted fields are lost), and the request shape is unverified (derived from compiled API client) requiring a dry-run preview before confirming. This goes well beyond annotations and fully informs the agent of the operational risks and requirements.

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 not verbose; it front-loads the main action, then the critical usage pattern, then the risk warning. Each sentence adds necessary information, and the structure is logical. It could be slightly trimmed (e.g., merging the unverified note), but it remains efficient for an agent.

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

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

The tool has two parameters, no output schema, and nested objects, but the description covers everything an agent needs: the prerequisite call, the replacement behavior, the confirmation requirement, the dry-run preview, and the unverified nature. The lack of an output schema is mitigated by the clear reference to preview dry-run, making the definition complete 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 coverage is 100%: both parameters have clear descriptions. The 'student' parameter is explained as the model from the form tools with edits applied, and 'confirm' is explained with its gating behavior. The tool description reinforces this by restating the pattern and the replacement consequence, adding value beyond the schema alone. Since the schema already covers meaning well, a 4 is appropriate.

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

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

The description states a clear verb ('Update') and resource ('a student profile'), and distinguishes itself from siblings by referencing the prerequisite form tools (mhlb_get_student_form / mhlb_new_student_form) and matching the pattern of other update tools like mhlb_update_order. An agent can immediately understand the tool's role.

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 when-to-use guidance: call mhlb_get_student_form first and send that model back with edits, emphasizing whole-record replacement. It does not explicitly name alternatives (e.g., mhlb_create_student for new records), but the prerequisite and critical warning make the intended usage clear. The guidance is highly directive and actionable, though a brief mention of when not to use it (e.g., for creation) would push it to a 5.

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 value by listing expected return fields, but it doesn't disclose anything about side effects, potential errors, or request behavior beyond what the annotations imply. The tool is simple and read-only, so 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 description is two concise sentences with the core action front-loaded. The first sentence states the purpose and lists fields without redundancy; the second provides a use case. 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?

For a zero-parameter, read-only tool with annotations providing safety context, the description covers the key aspects: what it returns (fields) and when to use it (session check). It lacks an explicit return format, but without an output schema and given the simple nature, this is minor.

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, so the baseline is 4. The description correctly omits parameter details, and the schema has nothing to clarify. Nothing is needed beyond the field list provided.

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 verb 'Get' and the resource 'signed-in My Hot Lunchbox account', and enumerates the specific fields returned (name, email, role, etc.). It also indicates a distinct use case as a session check, which differentiates it from siblings focused on orders, transactions, or students.

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 instruction 'Start here to confirm the session works' explicitly tells the agent when to use this tool first. It provides clear usage context without needing to name alternatives, as this is a unique initial verification step. It could be more explicit about not using it for other purposes, 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.