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

Beyond the destructiveHint annotation, the description reveals the soft-delete behavior (`removed from ordering but stays on historical orders`), role requirements, and the explicit instruction to confirm with the user. It also warns `DESTRUCTIVE operation`, adding meaningful safety context that annotations alone do not fully convey.

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

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

The description is compact but information-dense, front-loading the core action and soft-delete semantics before moving to the alternative and warnings. Every sentence earns its place: consequences, alternative, role, danger, and ID sourcing are all covered without fluff.

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

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

For an admin-only destructive mutation, the description covers when to use it, when not to, required role, confirm-before-invoking warning, ID provenance, and the post-archive behavior. With an output schema present, return-value documentation is not needed. The description is fully adequate 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 input schema already provides 100% coverage for both parameters, including where to source their values. The description reinforces this by telling the agent to get `restaurant_id` from `list_school_restaurants` and `menu_item_id` from `list_restaurant_menu_items`, but it does not add meaning beyond the schema's own descriptions. 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 uses a specific verb and resource: `Archives (soft-deletes) a menu item`, clearly distinguishing it from the sibling `update_restaurant_menu_item` path. It also states the operational scope (`Admin`) and the exact consequence (`can no longer be ordered`).

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 explains when to use archive vs. update: `To retire it from the restaurant menu without archiving, use update_restaurant_menu_item with is_active=false.` It also names the required role and tells the agent how to obtain the necessary IDs from sibling list tools.

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

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

Beyond annotations (destructiveHint=true), the description discloses concrete effects: reserved seats are released, full refund is credited to the user's wallet at that school, access is restricted to owner/coordinator, and the user must confirm before cancellation. This adds real behavioral context that the annotations do not 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?

Three concise sentences with no filler. The core operation is front-loaded, followed by consequences, permission constraint, and a clear safety warning. Every sentence contributes useful information.

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

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

For a one-parameter tool with an output schema and strong annotations, the description covers the identity of the affected ticket, the post-cancellation effects (seats and refund), the authorization constraint, and the required user confirmation. No significant calling context 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?

The single parameter is already fully documented by the schema (100% coverage), including the constraint that the ticket must belong to the caller and be cancellable. The description repeats the source of ticket_id but does not add new parameter-level semantics 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?

Description uses a specific verb ('Cancels'), specifies the resource ('one of the authenticated user's own event tickets'), names the required input source ('ticket_id from list_my_event_registrations'), and distinguishes itself from sibling cancel tools by targeting ticket registrations rather than lunch orders, volunteer signups, or the event itself.

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

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

It clearly frames when to use the tool: for a user's own event ticket cancellation, and it sets the condition that only the ticket owner or a coordinator may cancel. It also includes a confirmation requirement. However, it does not explicitly contrast with sibling tools like cancel_school_event or cancel_my_volunteer_signup, so some routing is left to 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 destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavior beyond that: the wallet refund, the rejection condition after labels are sent, and the user-confirmation requirement. There is no contradiction with the annotations, including idempotentHint=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?

Three short sentences with no filler: the core action, the timing limitation, and the destructive-action warning. It is front-loaded and 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 single-parameter mutating tool with an output schema and complete annotations, this covers the preconditions, the failure mode, the postcondition (refund), and the required user confirmation. Nothing essential for selecting or invoking the tool 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?

The schema fully documents order_id, including the source (list_my_lunch_orders) and the preconditions (finalized, labels not sent). With 100% schema description coverage, the description does not need to add parameter-level detail and does not meaningfully exceed what the schema already provides.

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

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

States a specific verb ('Cancels'), a resource ('finalized order'), and the resulting effect ('refunds the charge to the wallet'). The phrase 'finalized order' clearly distinguishes this from draft-focused siblings like discard_lunch_order_draft and create_lunch_order_draft.

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 gives the acceptable timing ('before order labels have been sent') and the when-not case ('after that the request is rejected and the order stands'). It also instructs the agent to confirm with the user before cancelling. It does not name a sibling alternative for drafts, but the finalized-order phrasing covers the primary routing decision.

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

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

Annotations already mark it destructive and non-read-only, but the description adds meaningful behavioral detail: it frees the shift slot for others, clarifies that no payment is involved, specifies authorization (volunteer/admin only), and explicitly instructs the agent to confirm with the user before proceeding. This goes far beyond the annotations and provides the agent with critical safety context. 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 compact and front-loaded, with each sentence serving a distinct purpose: the first states the action and effect, the second removes financial ambiguity, the third specifies authorization, and the fourth delivers the safety warning. There is no filler or redundancy, and the most critical destructive note is placed at the end for emphasis while still being quickly scannable.

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

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

For a simple one-parameter tool with annotations covering read-only/destructive/idempotent hints, the description provides ample context: effect on the shift, payment clarity, authorization, and confirmation requirement. It does not explicitly describe the return value, but an output schema exists, so that is not required. It also does not mention idempotency (e.g., behavior on double-cancel), but that is already covered by idempotentHint. Overall, it is almost 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%: the signup_id parameter already has a clear description stating it must come from list_my_volunteer_signups and belong to the caller. The tool description repeats this source but does not add new meaning or details (e.g., format, validation). Per the baseline rule for high schema coverage, a score of 3 is appropriate.

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

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

The description states a specific verb ('cancels'), resource ('volunteer signups'), and scope ('own'), and even references the source of the ID (list_my_volunteer_signups). It clearly distinguishes from sibling tools like cancel_my_event_registration or cancel_my_lunch_order by naming the unique resource. 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 gives clear context: it cancels only the authenticated user's own signups, from a specific list, and notes that only the volunteer or an admin can cancel. However, it does not explicitly contrast with related tools (e.g., cancel_my_event_registration) or state when not to use it beyond the ownership scope. There is implied usage guidance, but no explicit exclusions or alternatives are named.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the description is not required to restate that this is a destructive operation. It adds meaningful context beyond the annotations: the cancellation is permanent and cannot be reactivated, specific roles are required, and user confirmation is mandatory. This is strong behavioral disclosure, though it does not detail post-cancellation effects such as attendee notifications.

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

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

The description is compact and front-loaded: the action and permanence appear first, followed by sibling routing, role requirements, and the destructive confirmation. Every sentence carries necessary operational information with no filler.

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

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

For a single-parameter destructive admin operation, the description covers the core facts: what happens, what cannot happen afterward, which alternative tool to use, who may call it, what to confirm, and where the input comes from. Combined with the annotations and output schema, an agent has everything needed to select and invoke the tool 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?

The input schema already has 100% coverage, describing event_id as coming from list_school_events and noting the cancellation is permanent. The description repeats the 'get event_id from list_school_events' guidance but adds no fundamentally new parameter-level 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?

The description states a clear verb and resource ('Cancels a school event outright'), and immediately distinguishes it from siblings like update_school_event (for changes) and cancel_my_event_registration (for personal registrations). The 'ADMIN' prefix and emphasis on permanence make the tool's purpose unmistakable.

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

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

It explicitly says when NOT to use this tool ('For schedule, capacity, or price changes use update_school_event instead'), which is the key routing decision. It also gives a prerequisite ('Requires pac_cordinator or event_cordinator role'), a mandatory confirmation step ('DESTRUCTIVE - confirm with the user'), and the exact source for the input ('Get event_id from list_school_events').

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

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

Annotations already establish readOnly=false, idempotent=true, destructive=false, so the bar is lower. The description adds genuine context beyond those: 'nothing is charged until pay_lunch_order_draft commits it' discloses deferred financial impact, and 'plus nothing else' rules out hidden fees. No contradiction with the annotations exists — the description never claims read-only or destructive 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?

Purpose is front-loaded and each sentence earns its place: purpose, usage criterion, pricing/behavioral detail, lifecycle alternatives, and a FINANCIAL confirmation warning. Minor redundancy exists between sentence one ('nothing is charged until pay commits it') and sentence three ('plus nothing else until pay_lunch_order_draft'), which could be merged without loss.

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 output schema exists (covering return values), the schema documents parameter provenance via get_lunch_menu and get_my_context defaults, and the description covers financial impact, lifecycle routing, and a confirmation warning, this is nearly complete for a financial write tool. The one small gap is that the description doesn't state what happens on repeat calls with identical arguments — though idempotentHint=true partially covers this.

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

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

Schema coverage is 100%, so the schema documents all four parameters, justifying a baseline of 3. The description adds meaning on top: it explains the items structure as pairing a menu_item_id with a quantity and spells out the pricing computation ('sum of item prices times quantities plus nothing else'), which clarifies that price_cents is the unit price multiplied by quantity.

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

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

The description states a specific verb and resource — 'Creates an unpaid draft lunch order with one or more items' — and immediately distinguishes it from its lifecycle siblings: pay_lunch_order_draft commits it, update/discard change or abandon it. An agent can tell this tool apart from pay, update, and discard without opening any schema.

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

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

Gives explicit when-to-use criteria ('Use for multi-item orders or when the user should review the total first') and names the alternative tools for the next action (pay_lunch_order_draft) and for alterations (update_lunch_order_draft, discard_lunch_order_draft). It lacks an explicit when-not-to-use statement for the direct single-item/pay-now case, but the guidance is otherwise clear.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description goes beyond annotations by clarifying the new item starts active and available, and that only restaurant_id and name are required, with price_cents needed for ordering. It also warns it's a WRITE operation requiring user confirmation, adding behavioral context not captured in annotations. It doesn't contradict 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 concise, front-loading the essential purpose and critical requirements (admin, WRITE, required fields) in the first two sentences. It includes necessary operational details like role requirements and where to get restaurant_id without fluff. Slightly verbose with the role and confirmation details, but each 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 (7 params, admin role, WRITE operation) and that an output schema exists (so return format is covered there), the description covers the key operational aspects: required fields, role permissions, initial state, and reference to update tool. It doesn't mention potential validation or side effects, but these are minor given the annotations and output schema. Adequate 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 already provides descriptions for all 7 parameters (100% coverage), including examples like '550 = $5.50' for price_cents. The description adds minimal new semantic information, but does emphasize that only restaurant_id and name are required and that price_cents is important for ordering, which slightly enhances understanding of the parameter's role. Given the high schema coverage, a 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 tool creates a new menu item on a restaurant, a specific verb and resource, and mentions the requirement for restaurant_id and name. It also differentiates from the sibling update_restaurant_menu_item by noting that changes are made via that tool, and mentions the WRITE nature, which distinguishes it from read-only 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 explicitly says when to use it (to create a new menu item) and when to use the alternative (update_restaurant_menu_item for changes later). It also provides a prerequisite: obtaining restaurant_id from list_school_restaurants, and clarifies the need for admin roles, which prevents misuse.

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

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

Annotations already cover the write nature (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds value by requiring a coordinator role and mandating that creation happen only on explicit user request, which are important behavioral guardrails not present in annotations. It does not over-explain side effects, but for a create operation 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?

Three sentences with no filler: role, action, scope, sibling routing, and explicit-request guardrail are all front-loaded and actionable. 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 9-parameter create tool with a 100%-documented input schema and an output schema, the description covers the remaining non-schema essentials: auth requirements, sibling-tool disambiguation, and invocation policy. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description adds useful context that ticketing is optional and that the event is created at the active school, tying to ticket_price_cents/max_capacity and school_slug, but it does not substantially deepen parameter-level meaning beyond that 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?

States a specific verb ('Creates') and resource ('school event'), and clarifies scope ('at the active school') and optional ticketing. It also names the two sibling tools that handle modifications and registrations, so an agent can distinguish this from update_school_event and register_for_event.

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

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

Provides explicit role prerequisites, a WRITE / explicit-user-request condition, and direct routing to sibling tools for change (update_school_event) and registration (register_for_event). This leaves little ambiguity about when to invoke this tool versus alternatives.

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

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

Beyond the annotations, the description adds the role requirement, the need to confirm with the user, and the lack of an update path. These are meaningful behavioral details. It does not elaborate on the idempotent behavior hinted by annotations, but it does not contradict them either.

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

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

The description is compact and front-loaded with the most important signal ('ADMIN'), followed by the core action, sibling relationship, update limitation, role, and confirmation requirement. Every sentence adds value and there is no redundant filler.

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

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

Given that the schema fully documents parameters and an output schema exists, the description covers all essential operational context: admin scope, target school, purpose, role, confirmation, and update limitations. An agent has enough information to decide when and how to invoke this tool safely.

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

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

Schema description coverage is 100%, so the input schema already documents every parameter clearly. The description adds only indirect context about the 'active school' default for school_slug. This meets the baseline for full schema coverage without adding much parameter-specific value.

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

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

The description states a specific verb and resource ('Adds a restaurant to the active school') and explains the downstream purpose via create_restaurant_menu_item. It also clearly distinguishes itself from the sibling tool create_restaurant_menu_item by targeting restaurants rather than menu items.

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

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

The description provides explicit usage context: it is ADMIN-only, requires the pac_cordinator role, is a WRITE operation requiring user confirmation, and notes that no update tool exists so changes mean recreating or managing in the Paxaver admin. It also implicitly routes the agent to create_restaurant_menu_item for the next 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?

The description provides substantial behavioral context beyond the annotations: the operation is permanent, no refund exists because nothing was charged, the draft is simply deleted, and it explicitly warns to confirm with the user. It also emphasizes destructive behavior, matching the destructiveHint annotation without contradicting it.

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

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

The description is compact and front-loaded, with every sentence contributing necessary operational or safety information. The critical DESTRUCTIVE warning is included without redundancy or 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 single-parameter destructive tool, the description fully covers purpose, preconditions, side effects, alternatives, and user confirmation. Since an output schema exists, return-value details are not required here, and nothing essential is missing.

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

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

The input schema already fully describes order_id as the draft order ID from create_lunch_order_draft and requires draft status. The description reinforces this but adds no new parameter meaning beyond what the schema already covers, 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 identifies a specific verb and resource: 'Permanently discards an unpaid draft order.' It also differentiates from the sibling tool by specifying that it applies only to drafts and directing finalized orders to cancel_my_lunch_order.

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

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

The description explicitly states when to use the tool: the caller must own the draft, it must still be in draft status, and it must be unpaid. It also names the alternative for finalized orders and includes a clear confirmation requirement, leaving no ambiguity about usage.

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 the tool as read-only and non-destructive. The description adds value by specifying the precedence rule (date wins over month) and the default behavior (today when neither is provided), which are behavioral traits not captured by annotations. It does not mention pagination or response structure, but output schema is present.

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

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

The description is concise and well-structured, front-loading the primary purpose and key details. It covers parameter usage, defaults, and alternative tools in three sentences without redundant phrasing. Every sentence adds value.

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

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

Given the tool has 2 optional parameters, a comprehensive schema with 100% coverage, an output schema, and full annotations, the description is complete. It covers usage rules, parameter precedence, defaults, and cross-references to related tools. No critical information is missing for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds a small clarification about the precedence rule (date wins if both are passed), but otherwise does not introduce new semantic meaning beyond what the schema provides. This aligns with the baseline of 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 clearly states the tool returns the orderable lunch menu for the active school, including specific details (item names, prices, dietary tags, remaining quantity). It distinguishes itself from related tools like list_restaurant_menu_items and list_my_lunch_orders, so the agent can easily identify its unique 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 explicitly explains when to use this tool versus alternatives: it is for the orderable lunch menu, while list_my_lunch_orders is for already placed orders. It also provides clear usage logic for date vs. month parameters, including default behavior when neither is given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it is safe to call repeatedly, requires authentication, returns only the caller's own data, and returns live account state. It does not contradict annotations. A small gap is that it doesn't describe the output schema shape, but the output schema exists and the description covers the key behavioral traits.

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

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

The description is compact, front-loaded with the most important fact (read-only, safe to call repeatedly), and every sentence adds value: what it returns, why it matters, and when to call again. 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 an output schema and annotations covering safety, the description is complete. It explains the return contents, the authentication requirement, the privacy boundary, and the live-state caveat. An agent has everything needed to call it correctly and interpret its role in the broader toolset.

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 schema is trivially complete. The description adds value by explaining what the returned data contains and how it should be used, which is more relevant than parameter semantics for a no-parameter tool. Baseline 4 for zero params 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 ('lookup'), a clear resource (the caller's own context), and enumerates exactly what is returned (first name, active school, guardian students, role codes). It also distinguishes itself from siblings by framing it as the context-discovery call that other tools depend on.

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

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

The description explicitly says when to use it: as the context-discovery call, before other tools that need student_id or school_slug, and for admin-role checks. It also tells the agent to call again if the user may have switched schools or roles changed. This is strong usage guidance with no ambiguity.

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 destructiveHint=false, but the description adds substantial behavioral context beyond that: requires authentication, school-scoped data, live values reflecting orders/refunds, and the caution to recheck before assuming funds. It also emphasizes no side effects, which reinforces the read-only annotation without contradicting it.

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

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

The description is front-loaded with the most important fact ('Read-only lookup - never moves funds or has side effects') and every subsequent sentence earns its place: auth, scope, units, freshness, and usage guidance. It is detailed but not bloated, each clause adds distinct 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 zero-parameter tool with an output schema, the description covers everything needed to call it correctly: authentication requirement, per-school scoping, return format (cents and formatted), live-value semantics, and when to invoke it. An agent has all necessary 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 has zero parameters, so the baseline is 4. The description doesn't need to explain parameters because there are none; it instead explains what data the tool operates on (caller's balance, active school), which is the relevant semantic content.

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

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

The description names a specific verb and resource: it 'returns only the caller's spendable wallet balance.' It also scopes the operation precisely to the caller's active school, in cents and formatted, which separates it from any other balance-related query. This clearly distinguishes it from the mutation-heavy sibling list.

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

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

The description gives explicit when-to-use instructions: 'Call before pay_lunch_order_draft or register_for_event to confirm the user can cover the charge.' It also provides a when-not exclusion ('not needed for read-only lookups') and contextual scoping guidance about per-school balances.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this with 'Read-only, no side effects.' It adds valuable behavioral context beyond annotations: results are scoped to the active school, cancelled tickets are excluded, and the return payload includes ticket status values like paid and checked_in.

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

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

Four sentences with no fluff; the key behavioral claim is front-loaded and every sentence adds useful information. The only minor issue is that 'Read-only, no side effects' partly duplicates the annotations, but it is brief and harmless.

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 tool with an output schema and strong annotations, this description is complete: it defines scope, exclusions, returned fields, and links to the two most relevant sibling tools. An agent has everything needed to select and 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?

The input schema has zero parameters and schema description coverage is 100%, so the baseline of 4 applies. The description correctly focuses on output and scope rather than parameter syntax, and no parameter-level explanation 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 ('Returns') and a precise resource: the authenticated user's own event tickets at their active school, including the exact fields returned. It clearly differentiates itself from sibling list tools like list_school_events, list_my_lunch_orders, and list_my_volunteer_signups by scope and resource.

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 names the sibling tool list_school_events for events the user has not registered for, giving a clear when-to-use/when-not-to-use distinction. It also states that the returned ids are required by cancel_my_event_registration, which helps an agent decide to call this tool before attempting a cancellation.

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 destructiveHint=false, and the description adds non-obvious behavior beyond that: newest-first ordering, a ~100 record cap, filter precedence, and role-based visibility. Nothing contradicts 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 information-dense with no filler. Each clause earns its place: return fields, ordering, limit, filter semantics, fallback behavior, role scoping, and the pointer to a sibling tool.

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

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

For a read-only listing tool with an output schema, the description covers all needed invocation context: what is returned, ordering, limits, filter combination and precedence, default behavior, role-based access, and which sibling to use for menus.

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?

Although schema coverage is 100%, the description adds meaning beyond the schema: filters combine with AND, menu_date wins if both menu_date and month are provided, and student_id has ownership/role constraints. These behaviors are not inferable from the schema alone.

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

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

The description opens with a specific verb and resource: 'Returns lunch orders already placed - items, menu date, status, and total - for the authenticated user's students.' It clearly distinguishes this read tool from sibling create/cancel/update/order tools and from get_lunch_menu.

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 explains filter combination behavior (AND), menu_date vs month precedence, the no-filter default, and admin vs parent scoping. It also points to get_lunch_menu when the goal is ordering-eligible items, giving a clear alternative.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value beyond annotations by specifying that cancelled signups are excluded, the data scope (active signups at the user's school), and the dependency on cancellation. 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?

Four short sentences, each carrying distinct information: safety, return content, exclusion filter, and downstream usage. No filler, and the most critical information (read-only, what it returns) is front-loaded.

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

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

For a no-parameter tool with an output schema present, the description covers all necessary operational details: return fields, scope, exclusions, and the relationship to cancellation. 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 tool has zero parameters, so the input schema is empty and coverage is effectively 100%. The description appropriately doesn't dwell on parameters; the baseline for 0-param tools is 4, and no additional parameter explanation 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?

The description states a specific verb ('Returns') and resource ('volunteer signups'), with explicit fields returned. It distinguishes from siblings like list_my_event_registrations (different resource) and cancel_my_volunteer_signup (different action). The scope is clear: authenticated user's active signups at their school.

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 mentions that returned IDs are required by cancel_my_volunteer_signup, which gives a concrete use case and implies this tool is the precursor for cancellation. However, it doesn't explicitly contrast with other list tools (e.g., list_my_event_registrations) or state when not to use it, leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it returns inactive and unavailable items, requires pac_cordinator or lunch_cordinator role, and serves as a source of menu_item_id values for subsequent operations. These details go 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 information-dense and well-structured: it opens with the admin catalog scope, immediately handles the key sibling distinction, then covers downstream use, authorization, and parameter sourcing. Every sentence contributes unique value and none is redundant with the schema or annotations.

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

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

For a single-parameter read-only tool with an output schema, the description covers everything needed: purpose, scope, alternative tool, role requirement, and parameter provenance. The presence of an output schema means return-value documentation is already handled elsewhere, so no critical information is missing.

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

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

Schema description coverage is 100%, and the schema already documents restaurant_id as coming from list_school_restaurants. The description repeats this provenance, reinforcing it, but does not add new semantic detail about the parameter itself. Baseline 3 is appropriate because the schema carries the parameter documentation 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 uses a specific verb and resource: it 'lists the full menu-item catalog for a restaurant, including inactive and unavailable items.' It clearly distinguishes itself from get_lunch_menu by explicitly stating this is the catalog, not the orderable menu for a date. This provides strong sibling differentiation.

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

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

The description states when to use this tool versus get_lunch_menu, names downstream tools that consume its output (update_restaurant_menu_item, archive_restaurant_menu_item, schedule_lunch_menu_item), and gives the prerequisite source for the restaurant_id parameter (list_school_restaurants). It also states the required role, leaving no ambiguity about eligibility.

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 the tool as read-only and non-destructive, so the bar is lower. The description adds useful behavioral context beyond annotations: it returns upcoming events only, includes volunteer shifts and registration closure status, and is scoped to the active school. It does not contradict annotations and provides enough behavioral framing for a list 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 three sentences long and each sentence earns its place: the first states what is returned, the second explains how the returned IDs connect to downstream tools, and the third provides alternative-tool routing and the optional filter. It is front-loaded and free of filler.

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

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

For a read-only listing tool with an existing output schema, two optional parameters fully documented, and clear annotations, the description covers everything an agent needs: return contents, relationship to dependent tools, alternatives for own registrations, and optional filtering. Nothing important is missing.

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

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

Schema description coverage is 100%, so the schema documents both optional parameters (start_date and end_date) adequately. The description only says 'Optionally filter by date range,' which adds no new semantic detail beyond the schema's own descriptions. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool lists upcoming events for the user's active school and enumerates the included data (date, times, location, volunteer shifts, registration status). It distinguishes itself from related registration/signup tools by explicitly noting that event IDs feed register_for_event and shift IDs feed sign_up_for_volunteer_shift.

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 routing guidance: it says to use list_my_event_registrations / cancel_my_event_registration and list_my_volunteer_signups / cancel_my_volunteer_signup to review or undo the user's own registrations and signups. This tells the agent exactly when this tool is appropriate and when alternatives 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?

Beyond the annotations that already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral context: inactive restaurants are filtered out, the active school is the default, and role requirements are specified. The description is consistent with the annotations and provides extra filtering and authorization detail.

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: scope, filtering behavior, downstream integration, and role requirements are each covered in exactly the space they need. Despite listing multiple dependent tool names, every sentence earns its place with no filler.

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

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

Given a single optional parameter, an existing output schema, and read-only annotations, this description covers all necessary aspects: what is returned, what is excluded, default behavior, authorization, and how the results are consumed elsewhere. Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

The schema already documents the single parameter school_slug at 100% coverage, including its default-to-active-school behavior. The description reinforces that default but adds no new parameter-level information, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Lists') and resource ('active restaurants attached to a school'), with a clear default scope ('defaults to the active school'). This distinguishes it cleanly from siblings like list_restaurant_menu_items and create_school_restaurant by focusing on school-level restaurant retrieval.

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

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

The description explicitly notes that the returned restaurant_id values are required by several downstream tools, giving the agent a clear reason to call this tool first. It also states the required roles for accessing it. It does not explicitly compare against alternatives or state when not to use it, so it stops short of 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 signal readOnly=false, destructive=false, and idempotent=true, and the description adds valuable behavior: charging the wallet, optional tip donation, the rejection of already-finalized orders (supporting idempotency), and the no-card-payment limitation. The FINANCIAL warning further clarifies the risk profile.

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

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

The description is compact and front-loaded: the core action is stated first, followed by payment constraints, failure behavior, and the key exclusion. Every sentence carries operational weight, with no redundant or filler content.

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

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

Given a 2-parameter schema, an output schema, and rich annotations, the description covers the essential workflow: commit a draft, charge wallet, handle insufficient funds, and avoid misuse for new orders. No critical operational detail is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that tip_cents is added on top of the item total and that the combined amount is charged to the wallet, reinforcing the schema's note that tips go to the PAC.

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

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

The description states a specific verb and resource ('commits a draft order') and clearly distinguishes this tool from siblings like create_lunch_order_draft, discard_lunch_order_draft, and cancel_my_lunch_order. It also names the source of the draft order and the financial action 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?

It explicitly says this is not for new orders and directs the agent to use create_lunch_order_draft first. It also defines the payment constraint (wallet-only, no card) and gives a concrete failure-handling path: if balance is insufficient, tell the user to top up and retry.

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

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

Beyond the annotations, it discloses that all tickets go to the caller with no per-student split, that paid events debit the wallet, and that the call fails on insufficient balance, sold out, or closed registration. This significantly clarifies side effects; no statement contradicts the annotations, though the idempotentHint tradeoff is left to the annotation.

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 definition is compact and front-loaded: purpose first, then financial consequence, failure conditions, and sibling routing. The second sentence is dense but each 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 two-parameter registration tool, the description covers purpose, ticket allocation, costs, failure modes, and alternative tool, while an output schema exists for return values. Nothing essential is missing.

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

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

The schema covers 100% of parameters and already defines event_id and quantity; the description adds real semantic value by stating that quantity is tickets for the caller, enforces minimum 1, and explicitly rules out per-student splitting.

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: 'Registers the authenticated user for a school event and issues tickets to the caller.' It also differentiates itself from the volunteer sibling by explicitly directing volunteer use to sign_up_for_volunteer_shift.

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

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

It names the key alternative ('To volunteer at an event rather than attend, use sign_up_for_volunteer_shift') and gives conditional guidance for paid events with 'confirm before registering.' Failure conditions (sold out, registration closed, insufficient balance) further clarify when a call would not be appropriate.

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

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

Annotations already convey write/non-read, non-destructive, and idempotent behavior. The description adds value by specifying the role requirement, the 'WRITE - confirm with the user' confirmation protocol, and the scope limitation ('This only schedules the item'). No contradiction with annotations exists.

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 but information-dense: admin marker, action, scope limitation, sibling alternative, role requirement, confirmation prompt, and ID sources all appear in a few sentences. Key operational facts are front-loaded and 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?

With an output schema present and annotations covering idempotency/safety, the description supplies the remaining necessary context: role, confirmation, retirement alternatives, and ID source guidance. Nothing critical for selecting and invoking this tool is missing, though it could explicitly mention date format, but that is already 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 description coverage is 100%, so the baseline is 3. The description adds useful context by pointing to the source list tools for restaurant_id and menu_item_id, and by explaining available_qty as 'optionally capping portions' / 'omit for unlimited', which reinforces the schema semantics.

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

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

The description states a specific verb and resource: 'Puts a restaurant menu item on the orderable menu for a given date'. It explicitly distinguishes this action from retiring an item via update_restaurant_menu_item or archive_restaurant_menu_item, which clearly separates it from sibling tools.

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

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

The description provides when-not guidance by naming alternatives for retirement, states the required roles ('Requires pac_cordinator or lunch_cordinator role'), and instructs the agent to get IDs from list_school_restaurants and list_restaurant_menu_items. This leaves no ambiguity about when to use this tool.

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 meaningful behavioral context beyond the annotations: no payment is involved, the call fails when the shift is full or cancelled, and it explicitly labels itself as a WRITE operation requiring user confirmation before executing. These details complement the idempotentHint and destructiveHint 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?

Each sentence earns its place: the core action, the no-payment clarification, the shift_id disambiguation with sourcing instructions, the failure triggers, the guest alternative, and the confirmation guardrail. The description is compact but information-dense, with the main purpose front-loaded.

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

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

For a single-parameter tool with an output schema and complete annotations, the description covers everything an agent needs to invoke it correctly: parameter semantics, source of the ID, failure conditions, alternative usage, and user confirmation. There are no notable 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%, so baseline is 3. The description goes further by clarifying that shift_id refers to a shift within an event, not the event itself, and directs the agent to list_school_events for retrieval—value that the schema description alone does not fully convey.

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 ('Signs up'), names the resource ('volunteer shift'), and adds critical distinctions: it is for the authenticated user, involves no payment, and shift_id is a shift within an event, not the event itself. This clearly separates it from sibling tools like register_for_event and the event-level operations.

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 the tool is appropriate (signing up for a volunteer shift) and directly names the alternative for guests: 'To attend an event as a guest instead, use register_for_event.' It also instructs where to obtain shift_id via list_school_events, leaving no ambiguity about the prerequisite data source.

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 meaningful behavioral detail beyond the annotations: items are replaced wholesale, the total is recomputed from price times quantity, and only unpaid draft orders can be updated. It correctly complements readOnlyHint=false and destructiveHint=false by framing the operation as a controlled, reversible-enough edit with ownership 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 information-dense and front-loaded with the core behavior, but it contains minor redundancy about draft status ('must still be in draft status' and 'Only draft orders can be updated'). Still, it earns its length by covering ownership, replacement semantics, and post-finalization routing in a compact form.

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 3 parameters, an output schema, and no nested objects, the description covers all essential context: what changes, what is required, what the preconditions are, how totals behave, and how to handle finalized orders. An agent has enough information to invoke the tool correctly and to avoid destructive mistakes.

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%, but the description adds crucial semantics beyond the schema: items must be the complete replacement list, the update replaces existing items entirely, and the total is recomputed from price times quantity. It also clarifies that order_id comes from create_lunch_order_draft, reinforcing the schema's provenance note.

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 ('Replaces the items and/or menu_date') on a specific resource ('unpaid draft order'), and clearly scopes it to drafts not yet finalized. It also implicitly distinguishes this tool from siblings like discard_lunch_order_draft, pay_lunch_order_draft, and cancel_my_lunch_order by emphasizing draft-state editing.

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

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

The description explicitly says when to use the tool: the order must be owned by the caller and still in draft status. It also provides the alternative for finalized orders ('use cancel_my_lunch_order'), and instructs the caller to pass the complete items list and confirm with the user, giving clear operational 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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds critical behavioral context: partial update semantics (only provided fields change), the need to confirm changes with the user, role requirements, and the distinction from related tools. No contradictions.

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

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

The description is front-loaded with the core purpose and partial-update semantics, then flows through use cases, exclusions, role, and source IDs. Every sentence carries necessary information—no filler. It is compact given 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?

For a 9-parameter write operation with an output schema, the description covers purpose, usage, exclusions, role, and ID sourcing. Nothing essential for correct invocation is missing. The output schema handles return values, so description doesn't need to.

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 has 100% coverage with descriptive parameter comments, so baseline is 3. The description adds value beyond schema by highlighting price_cents as FINANCIAL (requiring confirmation) and is_active=false for retiring, and explains the partial-update behavior that affects all parameters. This pushes it above 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 verb ('partially updates'), a resource ('existing menu item'), and clearly distinguishes from siblings by naming schedule_lunch_menu_item and archive_restaurant_menu_item as alternatives for different operations. The use cases (renames, price changes, retiring) further clarify the tool's scope.

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 explains when to use this tool (partial updates for menu items) and when not to: day-level orderability goes to schedule_lunch_menu_item, permanent removal goes to archive_restaurant_menu_item. Also requires specific roles and confirms it's a WRITE operation, giving clear guidance on invocation 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 set readOnlyHint=false and idempotentHint=true, but the description adds crucial behavioral context: partial update semantics (omitted fields keep current values), role authorization, and a mandatory user confirmation step. It also notes that event_id comes from list_school_events, which is an operational behavior. No contradiction with annotations; the description enhances transparency significantly.

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

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

The description is front-loaded with the core semantic (partial update) in the first sentence, and each subsequent sentence delivers a distinct piece of action-guiding information: usage scenarios, alternative routing, role requirement, confirmation note, and ID source. No filler or redundant text; it earns every word.

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

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

Given the tool has 10 parameters, a single required field, an enum for status, and an output schema, the description is remarkably complete. It covers the operation's semantics, usage boundaries, authorization, safety confirmation, and data sourcing. The output schema handles return value details, so no further return explanation is needed. Nothing an agent needs to correctly invoke this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the global partial-update semantic (provided fields change, omitted fields retain values), which is not explicit in the schema. It also specifies the source of event_id. However, it does not elaborate on each parameter individually, relying on the schema for that, so 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 clearly states a specific verb and resource: 'Partially updates an existing school event'. It immediately differentiates from alternatives by explaining the partial update semantics and explicitly routing to cancel_school_event for outright cancellation. The usage examples (reschedules, capacity/price changes, status transitions) further clarify 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 explicitly states when to use the tool: 'Use for reschedules, capacity or price changes, and status transitions'. It also gives an explicit exclusion: 'Prefer cancel_school_event to cancel outright'. Additionally, it mentions role requirements (pac_cordinator or event_cordinator) and that it is a write operation requiring user confirmation, covering prerequisites and safety.

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