Paxaver

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

Goes well beyond the annotations, which only flag destructiveHint=true and non-idempotence. The description discloses concrete side effects: reserved seats are released and paid tickets are refunded in full to the user's wallet at that school. It also adds the permission condition and an explicit confirmation instruction.

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

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

Three tight sentences, front-loaded with the action and parenthetical sourcing, then consequences, then permissions, then the safety warning. Every sentence carries distinct, useful information with no padding.

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?

An output schema exists so return values need not be described. The description covers preconditions (cancellable ticket, ownership), side effects (seat release, refund destination), and the destructive-action confirmation — everything an agent needs to invoke it 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 coverage is 100% and the schema already documents ticket_id's origin and cancellability constraint. The description repeats the source (list_my_event_registrations) but adds no syntax or format detail beyond it, so baseline 3 is appropriate.

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

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

States a specific verb (Cancels) and resource (the user's own event ticket), scoping to ownership explicitly. An agent can distinguish it from cancel_my_lunch_order, cancel_my_volunteer_signup, and cancel_program_registration 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?

Names the source of the required ticket_id (list_my_event_registrations) and states the precondition that only the ticket owner or a coordinator can cancel. It stops short of explicitly naming alternative sibling tools, but the usage context is clear.

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

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

Beyond the destructiveHint=true annotation, the description discloses that cancellation refunds the charge to the wallet, explains the label-timing cutoff and rejection behavior, and advises confirming with the user. These details materially help an agent understand the consequences and prerequisites of the 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 three tight sentences with no wasted words. The core action, timing restriction, and destructive warning are front-loaded in an order that supports safe agent behavior.

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 mutation tool with annotations and an output schema, the description covers the necessary behavioral context: what it does, refund consequence, timing prerequisite, rejection outcome, and user confirmation. 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 coverage is 100%, so the order_id parameter is already fully documented in the schema. The description reinforces the finalized-order context but adds no new syntax, format, or constraint details beyond what the schema provides.

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

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

The description states a specific verb (Cancels) and resource (a finalized order), making the tool's core action immediately clear. It does not explicitly differentiate itself from sibling cancellation tools such as cancel_my_event_registration or cancel_program_registration, which keeps it from a perfect score.

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

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

The description gives a clear operational condition: it only works before order labels have been sent, otherwise the request is rejected. It does not mention alternative tools for managing lunch orders, but the timing constraint is sufficient guidance 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 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?

Annotations already declare destructiveHint=true, so the 'DESTRUCTIVE - confirm' line is partly redundant. The genuine added value is the disclosed side effect that the backend auto-promotes the next waitlisted registration, a non-obvious behavioral trait beyond annotations. Lacks visibility into any reversal or partial-failure behavior, but the waitlist disclosure is meaningful.

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 compact sentences with no filler, leading with the action and progressing to ID origin, side effect, and the warning. The coordinator sentence is useful but could be trimmed; overall well 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 destructive mutation with an output schema already covering return values and annotations covering safety, the description fills the remaining gaps: prerequisites (ID source), ownership scope, and the waitlist side effect. Nothing essential for correct invocation 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 both parameters are fully documented. The description restates that registration_id comes from register_for_program, which the schema already says, adding little beyond the structured fields. Baseline 3 is correct.

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) plus resource (program registrations) and scope (one of the caller's own students'), which cleanly separates it from the sibling 'my' cancellation tools. An agent can identify exactly what this mutates without opening the 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 clear context: the registration_id originates from register_for_program, and coordinators should use the Paxaver panel instead, implicitly excluding that audience. It lacks an explicit when-to-use vs the sibling cancel_my_* tools, so it's strong context but not a full when/when-not guide.

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 declare it as a non-idempotent mutation; the description adds the crucial behavioral facts that nothing is charged until pay_lunch_order_draft commits, that the server prices items (client-sent price ignored), and a FINANCIAL confirm-before-calling warning. These are non-obvious traits the annotations cannot convey.

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

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

Front-loads the purpose and is well organized, but 'nothing is charged until pay_lunch_order_draft' and 'plus nothing else until pay_lunch_order_draft' are somewhat redundant. Slightly dense but every sentence otherwise 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, return values need no explanation, and the description fully covers purpose, when-to-use, sibling routing, draft/pricing behavior, and a financial-safety caution. Complete for this tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it clarifies that each items entry pairs a menu_item_id with a quantity and that the draft total is the sum of item prices times quantities. It restates rather than contradicts the schema's pricing 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?

States a specific verb and resource ('Creates an unpaid draft lunch order') and immediately scopes it as unpaid/draft-only. It distinguishes itself from siblings by naming pay_lunch_order_draft, update_lunch_order_draft, and discard_lunch_order_draft, so an agent can separate this from list/order/cancel 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?

Gives an explicit condition for choosing this tool ('Use for multi-item orders or when the user should review the total first') and routes the agent to the right alternatives for changing or abandoning the draft. Nothing about when to use this vs the pay/update/discard siblings is left to inference.

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

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

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 this is a safe read (readOnlyHint, destructiveHint false), so the description's job is lighter. It adds real value beyond them by disclosing a dependency chain ('menu_item_id values returned are required by create_lunch_order_draft'), which an agent needs for correct sequencing.

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 front-loaded sentences with no filler. The scope and return contents come first, then parameter resolution, then cross-tool dependencies and alternatives.

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?

An output schema exists, so return-value detail is unnecessary, and the annotations cover the safety profile. The description fills the remaining gaps: filtering precedence, the create_lunch_order_draft dependency, and the alternative for placed orders.

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 exceeds that by adding precedence and default semantics not stated in the schema: today is used when neither is given, and date wins if both are passed. This clarifies behavior the schema descriptions leave ambiguous.

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

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

States a specific verb and resource ('Returns the orderable lunch menu for the user's active school') and enumerates what comes back (names, prices, dietary tags, remaining quantity). It is clearly distinguishable from create_lunch_order_draft and list_my_lunch_orders, which are named directly.

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 routes the agent: pass date for one day, month for a full listing, neither for today, and resolves the conflict ('if both are passed, date wins'). It also names the sibling to use for already-placed orders, so the when/when-not/alternative conditions are all covered.

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 read-only and non-destructive, and the description adds important behavioral context: authentication is required, only the caller's own context is returned, never another user's data, and live account state means it should be called again after school or role changes.

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?

Front-loads safety and authentication before explaining usage, which is effective. The enumeration of returned fields is somewhat redundant because an output schema exists, but the overall structure is clear and each sentence still contributes useful context.

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 discovery tool with annotations and an output schema, the description is complete. It covers authentication, data scoping, freshness, downstream dependency, and the meaning of key returned fields, leaving no meaningful gap 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 takes no parameters, so the baseline is 4. The description does not need to explain parameter semantics, though it does describe the returned fields, which is output information rather than parameter guidance.

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 read-only lookup and enumerates exactly what caller context is returned, including name, email, region, environment, school, students, and role codes. It clearly distinguishes itself from siblings by naming its role as the context-discovery call that supplies student_id and school_slug for most other 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 says this is the context-discovery call and explains the downstream dependency: most other tools need student_id or school_slug from here, admin-role checks come from roles, and account identity comes from email/region/environment. It also gives a clear re-call condition when the user may have switched schools or had role changes.

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/destructiveHint/openWorldHint, so the safety profile is covered; the description re-states it but adds genuinely new context: authentication requirement, per-school wallet scoping, live value reflecting orders/refunds, and a staleness warning. Only deduction is that the opening restates annotation-provided safety hints.

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?

Front-loaded with the read-only safety statement, then auth, scoping, currency, freshness, and usage routing in roughly priority order. Dense and every sentence carries information, though the read-only assertion partially duplicates the 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?

An output schema exists so return values need not be enumerated, yet the description still notes cents/formatting and liveness. Auth needs, scoping caveats, and the pre-payment use case are all covered for a zero-parameter 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?

Zero parameters, so the schema-based baseline is 4; there is nothing for the description to clarify. It does note the response is in cents and formatted, which is return-value context rather than parameter semantics.

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

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

States a specific verb+resource (get wallet balance) with tight scope: 'returns only the caller's spendable wallet balance at their active school'. The per-school scoping clause distinguishes it from sibling list tools like list_my_wallet_transactions and from generic balance reads.

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 tells the agent when to call it ('Call before pay_lunch_order_draft or register_for_event to confirm the user can cover the charge') and when not to ('not needed for read-only lookups'). Alternatives and the selecting condition are both 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the opening 'read-only lookup with no side effects - safe to call repeatedly' largely restates structured data, though it is not a contradiction. The description earns credit for genuine behavioral detail beyond annotations: cancelled shifts are excluded from the result and the caller's own signups are returned alongside the shifts.

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

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

It is a dense, front-loaded paragraph with no filler sentences; the safety claim leads and the ID-provenance rules follow. The opening clause duplicates the annotations, which costs a little efficiency, but every remaining sentence carries 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?

An output schema exists, so return values need not be explained, yet the description still maps output identifiers to the inputs of related tools, which is exactly the cross-tool knowledge an agent needs to chain calls. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and both parameters are already documented. The description still adds cross-tool semantics: event_id comes from list_school_events, and the returned shift 'id' values are the shift_id input elsewhere, tying parameter meaning to sibling tool contracts.

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 ('Returns one event's full detail for the selected school') and enumerates exactly what is included: date, times, location, capacity, ticket price, status, volunteer shifts with remaining slots, and the caller's signups. It distinguishes itself from the sibling list_school_events, which is named as the source of event_id.

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

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

It tells the agent where to get the required event_id ('from list_school_events') and how the returned shift and signup IDs feed sign_up_for_volunteer_shift and cancel_my_volunteer_signup, which is real routing guidance. It stops short of stating when NOT to use it (e.g. bulk retrieval vs. the list tool), so it is clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint 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?

Beyond the readOnly/idempotent annotations, it discloses that authentication is required, that only the caller's own data is returned, and explicitly what is never exposed (card numbers, payment-method identifiers, checkout links). It also documents cursor pagination, newest-first ordering, and that filters AND together.

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?

Front-loaded with the safety/auth statement and organized into terse clauses; dense but nearly every clause carries information. Slightly packed into one long paragraph, but 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?

With annotations covering safety and an output schema covering return values, the description fills the remaining gaps: auth requirement, data exposure limits, scoping defaults, filter combination, and pagination. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: all_schools is superseded by school_slug, student_id is limited to the caller's own students, and filters combine with AND. Cursor usage (pass returned nextCursor) is also explained behaviorally.

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+resource (list the caller's own wallet transaction history) and enumerates the returned fields, clearly distinguishing it from get_my_wallet_balance and the lunch/event list 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?

Gives concrete context: defaults to the active school, use all_schools for every school, use student_id to narrow to one student, and topUpUrl is for when the user asks to add funds. It does not explicitly say when to prefer this over get_my_wallet_balance, so not a full 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 establish the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds real value beyond that by disclosing the workflow chaining (event IDs feed register/get, shift IDs feed sign_up) and the 'active school' scope. It stops short of any auth or rate-limit context, but the workflow disclosure is substantive.

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?

Front-loaded with what the tool returns, then workflow routing. Every sentence is informative, though 'Optionally filter by date range' is mildly redundant given the schema already documents this, adding slight bulk.

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?

An output schema exists, so return values need no further explanation. The description supplies the scope ('active school'), the ID-chaining workflow, and the disambiguation against registration/cancellation siblings, leaving nothing an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so both date parameters (start_date, end_date, with format and inclusivity) are fully documented in the schema. The description only restates 'Optionally filter by date range' without adding syntax or semantics, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Returns upcoming events for the user's active school') and enumerates the returned fields (date, times, location, registration-closed flag). An agent can distinguish it from siblings like get_school_event or list_school_programs 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?

Explicit routing: event IDs feed register_for_event and get_school_event; get_school_event is required to reach volunteer shifts; and registration/signup review is directed to list_my_event_registrations / list_my_volunteer_signups alternatives. Names both when to use this tool and where to go instead.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so the bar is lower. The description still adds value by disclosing that only ACTIVE programs are returned and that enrollment counts (seats taken) are included, which annotations cannot convey.

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

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

Three tight sentences, front-loaded with the purpose before the returned fields and the downstream routing. The field enumeration is somewhat redundant given an output schema exists, which costs it a point but does not bloat the 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?

With full schema coverage, annotations covering the safety profile, and an output schema documenting return values, the description supplies everything else an agent needs: scope (active school, active programs), filtering, and the downstream consumer of the ids.

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 both parameters are self-documenting, so the schema carries the semantic load. The description restates the optional program_type filter but adds no enum guidance or format detail beyond it, making the baseline 3 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?

States a specific verb and resource ('Returns the active before/after-school, enrichment, and camp programs'), scopes it to the user's active school, and enumerates the returned fields. This clearly separates it from sibling list tools such as list_school_events or list_my_event_registrations.

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 tells the agent what to do with the result ('program ids feed register_for_program and the program administration tools') and notes the optional program_type filter, which is real usage context. It does not state when NOT to use this tool or name a competing list tool, but no plausible confusion exists among the siblings.

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

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

Annotations only cover the generic safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description adds genuinely new behavior: wallet-only funding, the specific failure mode when balance is insufficient, the remediation path, and a financial confirmation warning. It goes well beyond what the structured fields disclose.

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?

Roughly four compact sentences, each carrying distinct load: action, payment mechanics, failure handling, prerequisite, and risk warning. The most important constraints (wallet-only, prerequisite) are front-loaded rather than buried.

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

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

An output schema exists, so return values need not be described, and the description covers the remaining unknowns an agent needs: funding source, failure behavior, retry path, and the pre-call confirmation requirement. Nothing material is missing for a two-parameter mutation tool.

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

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

Schema description coverage is 100% and both parameters are documented there, including the draft-status constraint on order_id and the PAC donation on tip_cents. The description restates the PAC donation and the 'total' concept but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Commits a draft order ... and charges the wallet') and ties the input directly to the sibling that produces it (create_lunch_order_draft). An agent can distinguish this from create_lunch_order_draft, update_lunch_order_draft, and cancel_my_lunch_order 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 ('commits a draft from create_lunch_order_draft'), when-not-to-use ('Not for new orders - use create_lunch_order_draft first'), and the failure/retry path (top up via the Paxaver panel, then retry). It also names the excluded alternative ('no card payment is offered through 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?

Annotations only state readOnly=false, idempotent=false, destructive=false; the description goes well beyond that by disclosing the wallet-charging formula (quantity × ticket price), the failure modes (insufficient balance, sold out, registration closed), and the fact that the error payload contains a regional Paxaver top-up page. The financial-impact warning and the 'no per-student split' caveat are exactly the kind of context annotations cannot carry.

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?

Front-loads the core action, then semantics, then failure modes, then the sibling alternative, then the financial warning — a sensible priority order with no filler sentences. It is dense, with a long parenthetical that packs quantity semantics and the ticket-split clarification together, which costs a little readability.

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?

An output schema exists, so return values need not be described. For a non-idempotent, financially-impactful mutation, the description covers actor (authenticated user), cost mechanics, failure conditions, prerequisites (registration must be open, checked via the closed flag referenced in the schema) and the alternative tool — nothing material to correct invocation 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 schema already documents event_id, quantity bounds, and school_slug; baseline would be 3. The description still adds genuine semantic value by explaining what quantity means ('tickets bought for the caller, 1 to 20 - there is no per-student split') and how it maps to cost, which resolves an ambiguity the bare 'Number of tickets' schema text leaves open.

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+resource ('Registers the authenticated user for a school event') plus the side effect ('issues tickets to the caller'). It distinguishes itself from near-neighbours by naming sign_up_for_volunteer_shift as the alternate path for volunteering, so an agent can separate it from register_for_program and the volunteer tool without opening schemas.

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

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

Explicitly names the alternative tool and the condition that selects it ('To volunteer at an event rather than attend, use sign_up_for_volunteer_shift'), and adds an operational prerequisite ('confirm before registering' for paid events). It also enumerates the three failure conditions, giving the agent clear expectations before invoking.

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 cover the safety profile (readOnly=false, idempotent=false, destructive=false); the description goes well beyond that by disclosing the two possible outcomes ('registered' vs 'waitlist'), the atomic backend capacity check, the fee recorded (amountCents) in the response, and that no wallet charge occurs on this call. This is exactly the extra behavioral context annotations cannot express.

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?

Front-loads the action, then the outcome/fee behavior, then parameter provenance, then the write warning - a logical order with no filler. Slightly dense at four sentences, but each carries distinct 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 mutating registration tool with 4 params, an output schema, and annotations, the description covers outcome states, capacity semantics, billing implications, ID sources, and a confirmation warning. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds provenance for the two required parameters (program_id from list_school_programs, student_id from get_my_context), which is real meaning beyond the schema's 'must be your own student' 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?

States a specific verb (registers) and resource (one of the caller's own students, for a school program), and scopes it with concrete program categories (before/after-school care, enrichment, camp). An agent can distinguish this from the adjacent register_for_event without opening either 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 clear context: it names where each ID comes from (list_school_programs, get_my_context) and warns 'WRITE - confirm the student and program before calling.' It does not explicitly contrast with the sibling register_for_event, but the resource distinction makes routing 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?

Goes well beyond the annotations: revoking the session, the consequence that the next request forces a re-auth prompt, 'Deletes no data and changes no settings', and the app-owned-credential failure mode with its result message. This is exactly the side-effect and auth context the hints (destructiveHint=false, idempotentHint=true) cannot convey.

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

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

Three sentences, each load-bearing: what it does, when to call it, and the exception path. Front-loaded with the effect and the strict usage gate, 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?

An output schema exists, so return values need not be restated; the description instead supplies the outcome semantics ('next request makes the client ask the user to sign in again'). Nothing an agent needs to call this correctly is missing.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly adds no parameter detail, and schema coverage is trivially 100% for an empty object.

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?

Specific verb+resource: 'Ends the caller's current Paxaver sign-in for this MCP connection - revokes the session.' The scope is nailed down further ('for this MCP connection') so it cannot be confused with any of the cancel_* or list_* 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?

Explicit triggering condition: 'Call this ONLY when the user explicitly asks to sign out, log in again, or switch to a different Paxaver account or region.' It also names the case where the tool is the wrong route (app-held credentials) and points to the correct 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 declare a non-read-only, non-destructive, non-idempotent write, so the bar is lower; the description still adds value by noting no payment is involved, that the call fails when the shift is full or cancelled, and that the user should be confirmed before the write. It doesn't address duplicate-signup behavior or what the response contains, which is minor given the output schema.

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

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

Three tight sentences with zero filler: identity of the action, parameter provenance, failure conditions, sibling alternative, and the write confirmation warning, all 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 mutation with an output schema, the description covers everything an agent needs: auth subject, parameter source, failure modes, the alternative tool, and a confirmation requirement. Return values need not be explained since an output schema exists.

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

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

Schema coverage is 100% for the single parameter, so baseline is 3, but the description adds genuine meaning: shift_id identifies one shift within an event, not the event itself, and must be sourced from get_school_event. That disambiguation goes beyond the schema's own text.

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

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

States a specific verb and resource ('Signs the authenticated user up for a specific volunteer shift') and immediately scopes what shift_id refers to versus the event, which separates it from sibling register_for_event and cancel_my_volunteer_signup.

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?

Explicit routing: says to obtain shift_id from the event's shifts via get_school_event, and names register_for_event as the alternative for attending as a guest. It also states the failure condition (shift full or cancelled), leaving little to inference.

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

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

Annotations cover the safety profile (destructiveHint=false, idempotentHint=true), and the description adds real behavioral context beyond them: ownership requirement, draft-status requirement, wholesale item replacement semantics, total recomputation from menu price times quantity, and an explicit WRITE/confirm-with-user instruction. The wholesale-replace wording is consistent with 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?

Front-loads the action and scope, then hooks, then constraints, then the confirmation cue. Dense but every clause carries information; slightly overpacked with dash-separated conditions, though nothing is padding.

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?

An output schema exists so return values need not be described. Everything an agent needs to call this correctly is present: prior step, ownership, status gating, destination of replaced items, total recomputation, and the write-confirmation obligation.

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, but the description adds a genuine semantic constraint not spelled out in the schema fields: items must be passed as the COMPLETE list because they replace existing items wholesale, and the total is recomputed. order_id provenance (from create_lunch_order_draft) is also reinforced.

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+resource (replaces items/menu_date of an unpaid draft order) and scopes it precisely to pre-finalization drafts. It is clearly distinguishable from its siblings create_lunch_order_draft, pay_lunch_order_draft, discard_lunch_order_draft, and 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?

Explicitly states the preconditions (caller must own the draft, it must still be in draft status) and the when-not case with the alternative: 'once finalized, use cancel_my_lunch_order.' Provenance of order_id is named via create_lunch_order_draft, so the agent knows the whole flow.

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