paxaver-mcp

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

The description goes beyond the destructiveHint annotation by adding that cancellation is irreversible, that user confirmation is mandatory, and that specific roles are required. These are exactly the behavioral details an agent needs before invoking a destructive 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 tight sentences with no filler. Every sentence contributes essential information: what the tool does, who may use it, and why extra caution is required.

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 destructive operation with annotations and an output schema already present, the description is nearly complete. It could be slightly stronger by linking to how to obtain the event_id or by referencing related event-management tools, but nothing essential for safe 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 0%, and the description does not elaborate on event_id at all beyond implying that an event is being cancelled. The parameter name is self-explanatory, but the description fails to compensate for the complete lack of schema-level documentation.

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-plus-resource construction: 'Cancels a school event.' It clearly differentiates from siblings like cancel_order and update_event because it targets events and performs cancellation rather than modification.

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

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

The description provides clear role prerequisites and a critical user-confirmation requirement before acting. It does not explicitly name alternative tools or state when not to use it, but the context is sufficiently clear for an agent to select it for an admin event-cancellation request.

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 destructiveHint=true, and the description reinforces this by stating the operation is DESTRUCTIVE and refunds the wallet. It also discloses the rejection condition (labels already sent) and idempotency, both 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 compact, with the core purpose and condition in the first sentence followed by safety-critical caveats. Every sentence adds information: refund, destructive confirmation, rejection condition, idempotency.

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 a high-coverage schema and output schema present, the description covers the key behavioral aspects: scope, refund, destruction, rejection, idempotency, and user confirmation. No important gaps are evident.

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 order_id is fully documented in the schema (100% coverage), so the description doesn't need to add param detail. It provides no extra meaning beyond the schema, matching 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?

States a specific verb 'Cancels' with resource 'finalized order' and a condition ('if labels have not been sent yet'), which distinguishes it from order-creation/finalization siblings. The behavior is unambiguous even without reading 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?

Description explicitly scopes valid use: only finalized orders, and only before labels are sent; it warns that cancellation is rejected if labels have already been sent. It also instructs to always confirm with the user before cancelling, 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?

Beyond the annotations, the description discloses that this is a FINANCIAL + WRITE operation, requires user confirmation, is idempotent, and does not finalize payment. This adds meaningful behavioral context beyond readOnlyHint=false and destructiveHint=false.

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

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

The description is compact and front-loaded: action, required parameters, draft lifecycle, then the critical financial/write confirmation warning and idempotency. 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?

The description covers the essential operation, required fields, draft vs. finalized behavior, confirmation requirement, and idempotency. With an output schema present and annotations provided, this is largely complete, though a brief mention of when to prefer the sibling order_lunch would make it fully self-contained.

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 75%, so most parameter semantics are already documented. The description restates the required top-level fields and the shape of each item, which helps, but it does not add deeper meaning such as currency units, date format nuances, or how idempotency interacts with parameters.

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

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

The description clearly states the verb (create), the resource (draft lunch order), and the scope (for a student). It also distinguishes this tool from finalize_order by explaining that the result is a draft, not a committed order.

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

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

The description gives clear usage context: create a draft, then call finalize_order to commit. It also warns to confirm order details with the user before calling. It does not explicitly compare against the sibling order_lunch, so it stops short of a full when-not-to-use explanation.

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

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

The description discloses meaningful behavioral traits beyond what annotations provide: the role prerequisite, the confirm-before-create guardrail, and the instruction not to create events without explicit user request. These traits complement the annotations (readOnlyHint=false, destructiveHint=false) rather than contradict them, since creating is a write but not a destructive 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 four short sentences, each carrying distinct information: purpose, role requirement, confirmation guardrail, and explicit-request constraint. The last two sentences are partially redundant ('confirm details' versus 'do not create without explicit user request'), but there is no fluff and the core purpose 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?

With an output schema present, return-value documentation is unnecessary, and the description covers purpose, auth, and invocation safety well. It leaves gaps on sibling differentiation (register_event is an ambiguous competing tool) and parameter semantics given the low schema coverage. It is adequate but not complete for a 9-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?

Schema description coverage is only 33%, yet the description contributes zero parameter-level guidance. Format-sensitive fields like starts_at and ends_at lack any format hints, and max_capacity has no meaning or unit clarification. The description fails to compensate for the low 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 states a specific verb and resource: 'Creates a school event.' This clearly identifies the operation and naturally distinguishes it from update_event and cancel_event among the siblings. However, it does not differentiate from the similarly-named sibling register_event, which could plausibly perform a related creation task.

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

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

The description provides clear usage context: a pac_cordinator or event_cordinator role is required, and the tool should only be invoked on explicit user request after confirming details. It does not, however, state when not to use this tool or name alternatives, such as update_event for modifying existing 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?

The readOnlyHint=false annotation already signals a mutation, and the description repeats this with 'WRITE operation', but it adds a specific role requirement (pac_cordinator or lunch_cordinator) that is not in the annotations. It does not describe failure modes, idempotency, or effects on existing data, but the annotation profile covers the basic write/destructive expectations.

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 very short and front-loaded with the ADMIN tag, with no wasted sentences. It loses one point because 'WRITE operation' largely repeats readOnlyHint=false and 'ADMIN' repeats the annotation title, but the overall structure is efficient.

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

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

For a 7-parameter create operation with zero parameter descriptions, the description is too sparse to support fully correct invocation: parameter semantics, side effects, and sibling-tool routing are all missing. The presence of an output schema reduces the return-format burden, but the input side remains substantially underdocumented.

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

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

Schema description coverage is 0%, so the description must carry the burden of explaining the 7 parameters. It only implies restaurant association and menu-item creation, leaving restaurant_id, name, calories, cost_cents, description, ingredients, and price_cents without semantic or unit context.

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 ('Creates'), a concrete object ('menu item'), and a parent scope ('for a restaurant'), which cleanly distinguishes this from siblings like create_restaurant, update_menu_item, and delete_menu_item. The ADMIN prefix adds an access boundary without obscuring the operation.

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

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

There is no explicit when-to-use guidance or mention of alternatives such as update_menu_item for modifying existing items or set_daily_menu for daily menu assignments. The role requirement implies an admin-only caller but does not help an agent decide between this and related 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?

Although readOnlyHint=false already indicates a write operation, the description adds valuable behavioral context: it requires the pac_cordinator role, is an admin operation, and the agent should confirm with the user before invoking. This goes beyond the annotations and meaningfully guides invocation.

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 short, front-loaded sentences with no filler. The critical access requirement and user-confirmation instruction are included without bloating 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?

The description provides purpose, role information, and confirmation guidance, and an output schema exists to cover return values. However, the complete absence of parameter guidance leaves an agent without enough information to confidently construct a valid call, especially for tax_percent and school_slug.

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

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

Schema description coverage is 0%, and the description compensates with nothing about the parameters. The required 'name' is never mentioned, and there is no guidance on the meaning or format of 'school_slug', 'description', or 'tax_percent', nor how 'active school' relates to 'school_slug'.

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

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

The description clearly identifies the operation ('Creates a restaurant'), the scope ('for the active school'), and the admin-only nature. This distinguishes it well from siblings like create_menu_item, create_event, and create_draft_order, which target different resource types.

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 the intended context—creating a restaurant for the active school—and the required role ('pac_cordinator role'). It does not explicitly name an alternative tool or mention when not to use it, but the resource-specific purpose makes the usage context reasonably clear.

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

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

Discloses three behavioral facts beyond annotations: the operation is a soft-delete, it requires specific admin roles, and the user should be asked for confirmation before executing. The annotations only flag destructiveHint, so the description adds meaningful transparency 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?

One short, front-loaded sentence conveys the key facts: admin scope, soft-delete behavior, role requirements, and user confirmation. Every word earns its place with no redundancy.

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

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

Combined with annotations and an output schema, the description covers the essential decision-making facts: authorization, destructive intent, soft-delete semantics, and confirmation. It does not detail what soft-delete means practically (e.g., whether the item disappears from menus or can be restored), which is a minor gap.

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

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

The schema has no parameter descriptions and the description does not explain 'restaurant_id' or 'menu_item_id'. While the names are self-explanatory, the description adds no semantic nuance beyond the schema itself, and with 0% schema coverage it was expected to compensate.

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?

Begins with 'ADMIN: Soft-deletes a menu item', naming the exact action and resource with a specific verb. 'Soft-deletes' distinguishes it from permanent deletion, and the resource name distinguishes it from sibling create/update/list 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?

States the required roles ('pac_cordinator or lunch_cordinator') and explicitly says to confirm with the user before performing the destructive operation. It does not explicitly name alternatives or say when not to use it, but the tool name and admin-only scope make the intended use reasonably clear.

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

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

Beyond the annotations, it explicitly flags this as a FINANCIAL + WRITE operation, mandates user confirmation, and states idempotency. These are material behavioral disclosures that an agent needs, and they do not contradict the readOnlyHint/destructiveHint 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: core purpose, optional parameter, critical warning, and idempotency. Everything earns its place and is front-loaded for quick scanning.

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

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

For a financial write operation it covers the action, payment effect, user-confirmation requirement, idempotency, and optional tip. With an output schema available and only two well-documented parameters, nothing essential is missing.

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

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

Schema coverage is 100%, and the description adds no meaning beyond the schema's parameter descriptions. It mentions the option to include tip_cents and its PAC donation purpose, matching the schema, but doesn't enrich parameter semantics further.

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

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

States a specific action (finalizes), a precise resource (draft order), and the key effect (deducts payment from wallet). This clearly differentiates from sibling tools like create_draft_order or order_lunch by focusing on the finalization/payment step.

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

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

The instruction to confirm with the user before calling provides a clear trigger condition for this financial/write action. It doesn't explicitly name alternatives or state when not to use it, but the draft-order scoping and optional tip parameter make the intended context 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?

The description adds useful behavioral detail beyond the readOnlyHint annotation: it returns the menu for the active school, accepts either date or month, and defaults to today's menu when neither is provided. It also explicitly says 'Read-only,' which aligns with the annotations. No contradictions exist.

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 short sentences and front-loads the core purpose. Every sentence adds useful information: what it returns, the parameter options, the default, the read-only nature, and the intended downstream use. No filler or redundancy.

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

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

For a simple read-only tool with two optional parameters and an output schema, the description is fully sufficient. It covers the active-school context, parameter selection behavior, default behavior, and intended use case. The output schema handles return-value details, so 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?

Even though the schema already documents the two optional parameters and their formats, the description adds the important semantics that they are alternatives and that omitting both yields today's menu. This clarifies mutual exclusivity and default behavior, adding value 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 specific verb and resource: 'Returns the daily lunch menu for the user's active school.' It also connects to a concrete downstream use ('find menu_item_id values for order_lunch'), which makes its role among the sibling tools clear. The daily-menu resource is distinct from monthly orders, events, wallet, and user-info tools.

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

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

It clearly explains when the tool is useful: to retrieve menu items and get menu_item_id values for ordering lunch. It also covers the optional input behavior with date/month/today defaults. It does not explicitly state when not to use it or name alternatives, 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 indicate readOnlyHint=true and destructiveHint=false, and the description mirrors this with 'Read-only.' Beyond that, it adds meaningful context: role requirement (pac_cordinator or lunch_cordinator) and the 'active school' scoping. This helps the agent understand permissions and context beyond what annotations capture.

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

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

The description is two tightly packed sentences: it opens with 'ADMIN:' to set access expectations, then states the operation, scope, and role requirement. No filler or redundant information, and the read-only note is short. Every phrase earns its place.

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

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

For a simple one-param, read-only tool with a full output schema and no nested objects, the description fully covers what an agent needs to select and call it: it defines the use case, the auth requirement, and the scope. The date format is already in the schema, so no further explanation is needed.

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%, with menu_date documented as 'YYYY-MM-DD'. The description adds only 'on a given date,' which maps to the same parameter but does not add new semantic detail. The baseline of 3 is appropriate because the schema carries the descriptive 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 states a specific verb ('Returns'), a specific resource ('all orders for the active school on a given date'), and an access scope ('ADMIN', 'Requires pac_cordinator or lunch_cordinator role'). This clearly distinguishes it from siblings like get_monthly_orders (monthly aggregation) and get_orders (general order lookup).

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

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

The description provides clear context: this is an admin-only tool for retrieving all orders on a specific date for the active school. It does not explicitly name alternatives or say when not to use it, but the daily scope and role requirement make the intended use evident without 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, so the behavior is partially known. The description adds 'Read-only' (repeating the annotation) and the notion of a summary, but does not disclose how missing month is handled, what the summary contains (counts, revenue, statuses), or any other behavioral traits. No contradiction, but little novel disclosure.

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 short, purposeful sentences. The main purpose is front-loaded, followed by the key filtering options and the read-only guarantee. Every sentence earns its place with 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?

For a simple read-only tool with two optional parameters, a fully described schema, and an output schema present, the description is mostly complete. The only notable gap is the unspecified behavior when no month is provided (e.g., current month vs. all months), but that is a minor ambiguity rather than a blocking omission.

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%, with the schema already documenting 'YYYY-MM' and 'must be your own'. The description merely restates the existence of optional filters without adding format, constraints, or default behavior. Baseline of 3 is appropriate since the schema carries the semantic load.

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

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

The description clearly states the specific verb and resource: 'Returns a monthly summary of orders.' This distinguishes it from sibling tools like get_orders (likely more granular) and get_daily_menu by the temporal aggregation level.

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

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

The description implies usage through 'monthly summary' and optional filters, but it never explicitly contrasts with alternatives like get_orders or states when to prefer this tool. There is no when-to-use versus when-not-to-use guidance, leaving the agent to infer based on the name.

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 non-destructive behavior, so the description only needs to add context beyond that. It adds that orders are scoped to the authenticated user's students and limited to 'recent,' which is useful. However, it does not define 'recent' or disclose ordering/pagination, so the added behavioral context is moderate.

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 short and front-loaded with the core purpose. Minor redundancy exists because 'Read-only' restates an annotation, but it is still economical and easy to parse.

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

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

For a simple read-only tool with one optional parameter and an output schema, the description provides enough to invoke it correctly. The only notable gap is the undefined meaning of 'recent,' but that is not likely to prevent correct usage given the output schema and annotations.

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 covers student_id with 100% description coverage, including the constraint that it must be the user's own student. The tool description merely restates 'Optionally filter by student_id' without adding any new meaning, so the baseline 3 applies.

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

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

The description states a specific verb and resource: it returns recent lunch orders for the authenticated user's students. It also distinguishes itself from siblings like get_monthly_orders (recent vs. monthly) and order_lunch (returns vs. creates), so the agent can tell it apart.

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

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

The description gives clear context: it is for reading recent lunch orders and optionally filtering by a student. It does not explicitly mention when not to use it or name alternatives such as get_monthly_orders for a broader history, so it stops short of full routing guidance.

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

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

Annotations already carry readOnlyHint=true and destructiveHint=false, so the safety profile is externally supplied. The description adds the active-school scoping and optional date-range filtering, but it does not disclose ordering, pagination, or how 'upcoming' is bounded. This is useful context but not rich behavioral disclosure.

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

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

Two sentences, action-first phrasing, and the optional filter details are packed into a single clear clause. There is no filler or redundant explanation beyond the brief read-only note, which remains useful if the description is read standalone.

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

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

For a read-only tool with two optional parameters and an output schema, the description covers the target, scope, filter options, and safety profile. An agent can correctly decide whether to call it and construct a valid request without missing critical information.

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

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

Schema description coverage is 100% and each parameter already documents the YYYY-MM-DD format. The description adds that start_date and end_date form an optional date range, but this is largely inferable from the parameter names and the optionality is already present in the schema. The added semantic value is moderate.

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 concrete action ('Returns upcoming events') and a precise scope ('user's active school'), distinguishing it from sibling tools about orders, menus, and wallet data. It also contrasts with register_event, which is an event write operation rather than a read.

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 context is clear: use this to fetch upcoming events for the active school, with optional start/end date filtering. However, it does not explicitly name an alternative for other event-related operations or state when not to use this tool, so it stops short of fully explicit usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, and the description partly restates that with 'read-only operation.' It does add a small amount of non-annotation context by framing the result as scoped to the *authenticated* user, implying an auth prerequisite, but it says nothing about failure modes (e.g., when no session exists) or what the agent should do if context is missing.

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

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

Three short sentences, front-loaded with what is returned and immediately followed by the mandatory-call directive. The trailing 'read-only operation' clause is the only wasted words, since annotations already carry that hint.

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 full annotation coverage and an output schema, nothing further is needed. The description supplies the one thing structured fields cannot: the ordering constraint that this call must precede all others.

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 and there is no param-level meaning to add. The field enumeration in the description is return-value information rather than parameter semantics, and the presence of an output schema makes that enumeration largely redundant.

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

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

The description names a specific resource (the authenticated user context) and enumerates exactly what comes back: first name, active school, guardian students, and roles. That level of detail makes it unmistakable against siblings like get_wallet_balance or get_orders.

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

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

It gives an explicit, unambiguous invocation rule: always call this first before any other tool to establish context. For a zero-parameter bootstrap tool this is precisely the guidance an agent needs to sequence its calls, and no exclusion clause is required because there is no competing 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 readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only.' It adds useful scoping context about the authenticated user and active school, but it does not disclose anything beyond that, such as whether balance can be zero, stale, or require refresh. With annotations already covering the safety profile, a 3 is appropriate.

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

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

Two compact sentences deliver the core function, scoping, read-only nature, and usage context. Every sentence earns its place, and the main verb and resource are front-loaded.

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

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

For a simple zero-parameter, read-only getter with an output schema already present, the description is fully sufficient. It states what is returned, for whom, at what scope, and when to use it. 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?

The tool has zero parameters and the input schema is empty, so there is nothing missing from the description. The description correctly implies the only implicit inputs are the authenticated user and active school context. Baseline 4 is appropriate for a zero-parameter tool.

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: 'Returns the current wallet balance for the authenticated user at their active school.' It is distinct enough from siblings like get_wallet_status, but it never explicitly contrasts itself with that sibling, so some ambiguity remains about why both wallet tools exist.

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 usage context: 'Use this to check funds before ordering lunch.' While this is a strong signal for when to call the tool, it does not name alternatives or provide when-not-to-use guidance, 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 declare readOnlyHint=true and destructiveHint=false, so the description's 'Read-only' adds little. It does add value by specifying the returned components (balance, transactions, pending deposits), but no additional behavioral traits such as freshness, limits, or error conditions are disclosed.

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

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

Two short sentences with no wasted words. The main return content is front-loaded, and the usage hint is appended cleanly.

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

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

For a zero-parameter read-only tool with an output schema and clear annotations, the description is essentially complete. The only minor gap is not explicitly distinguishing when to prefer get_wallet_balance over this tool, but the content difference is implied.

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 there is no schema burden to compensate for. The description appropriately avoids inventing parameter details.

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

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

States a specific verb ('Returns') and resource (wallet status) with a clear scope: balance, recent transactions, and pending deposits. This differentiates it from sibling get_wallet_balance, which presumably returns only the balance.

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?

'Use this for a wallet overview' gives clear context for when the tool is appropriate. It does not explicitly exclude get_wallet_balance or name an alternative condition, but the overview framing is clear enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying the exact roles required ('pac_cordinator or lunch_cordinator'), which is not present in annotations. It does not contradict annotations and provides meaningful behavioral context beyond the 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?

The description is a single, tightly written sentence with no filler. It front-loads the access level, then states the operation, the role requirement, and the read-only nature in order. Every word contributes value.

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

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

For a simple list operation with one required parameter and an output schema, the description is largely sufficient. It communicates the access control and read-only behavior, though it does not mention pagination, ordering, or filtering. Given the tool's simplicity and the presence of an output schema, this is a minor gap.

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

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

Schema description coverage is 0%, so the description needed to compensate but does not. The description mentions 'for a restaurant' but never explains the restaurant_id parameter, its expected format, or how it relates to the list. An agent must infer the parameter meaning from its name 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 states a specific verb and resource: 'Lists menu items for a restaurant.' The 'Read-only' qualifier and 'ADMIN' prefix clearly distinguish it from sibling mutation tools like create_menu_item, update_menu_item, and delete_menu_item. This is immediately actionable.

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: this is an admin-only, read-only operation that requires a specific role. It does not explicitly name alternatives or state when not to use it, but the role requirement and read-only nature provide enough guidance for an agent to select it appropriately among menu-related 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 already mark readOnlyHint and destructiveHint, so the duplicate 'Read-only' adds little. However, the description adds valuable behavioral context beyond annotations by specifying the required roles and the active-school scoping behavior.

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

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

The description is a single concise sentence with the ADMIN marker front-loaded, followed by scope, role requirements, and read-only status. Every element is directly useful and there is no fluff.

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

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

The tool is simple: one optional parameter, an output schema is present, and safety annotations are provided. The description adds the missing human-context elements, roles and active-school scope, making it complete enough for an agent to invoke 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 covers 100% of the parameter description, including the default-to-active-school behavior. The description does not add new parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Lists', the resource 'restaurants', and the scope 'for the active school'. It is easily distinguished from sibling tools like list_menu_items or create_restaurant because the resource and admin context are explicit.

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

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

The description provides clear context by labeling this as an ADMIN operation and explicitly listing the allowed roles (pac_cordinator, pac_member, lunch_cordinator). It does not name alternatives or when-not-to-use cases, but the role and resource scope make the intended usage 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 annotations, the description reveals that this is a financial write operation, payment is deducted from the wallet, the agent must confirm details with the user before calling, and duplicate calls with the same idempotency context are safe. This is rich, actionable behavioral context and does not contradict the annotations.

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

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

The description is three focused sentences with no filler. It front-loads the action, then covers required data, optional parameters, side effects, confirmation requirements, and idempotency — 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 financial write tool with an output schema present, the description covers everything needed to invoke it correctly: required parameters, where to get them, default behavior, side effects, confirmation obligation, and idempotency behavior. No critical gap remains.

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 all parameters with 100% coverage, so the baseline is 3. The description adds value above the schema by explaining where menu_item_id and student_id come from and the student_id default behavior, making it more helpful than 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 uses a specific verb ('Places') and resource ('a lunch order') and defines the guardian scope clearly. It does not explicitly distinguish itself from siblings like create_draft_order or finalize_order, so it falls short of a 5.

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

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

The description gives clear prerequisites and data provenance: menu_item_id must come from get_daily_menu, menu_date is YYYY-MM-DD, and student_id defaults to the user's first student if only one. It does not explicitly state when-not-to-use or name alternatives, so it misses the top score.

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

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

The description explicitly labels the operation as a WRITE operation, instructs the agent to confirm with the user, and notes idempotency. These add behavioral context beyond the annotations (readOnlyHint: false, destructiveHint: false), which only imply mutation. This is useful for an agent deciding how to present the action to a user.

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 tight and front-loaded: it opens with the core action, then lists the required parameter, optional parameter, and behavioral warnings. Five short sentences are slightly choppy but every sentence earns its place. 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?

For a simple two-parameter write operation, the description covers the essential context: who performs the action, what is required, the write nature, confirmation requirement, and idempotency. It does not describe return values, error cases, or capacity checks, but with only two parameters and annotations present, this is adequate.

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

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

The input schema already contains 100% parameter coverage with descriptions for both event_id and quantity, including the default of 1. The description adds no additional semantic detail beyond echoing 'Requires event_id' and 'default 1', so it stays at the baseline for schema-covered parameters.

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: 'Registers the authenticated user for a school event.' This clearly distinguishes the tool from siblings like create_event (which creates an event) and cancel_event (which cancels an event). The phrase 'Requires event_id' further clarifies the primary input needed.

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 implicitly defines when to use this tool: whenever an authenticated user needs to register for a school event. It provides clear context and prerequisites ('Requires event_id') but does not explicitly name alternatives or state when not to use them. This is solid context without exclusion criteria.

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 show readOnly=false and destructive=false, and the description builds on that by adding the authorization requirement and the assignment behavior. It does not explain whether an existing menu entry is overwritten, but with annotations already covering the safety profile, adding auth context is valuable and sufficient.

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

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

The description is short and front-loaded with the ADMIN marker, then gives the core semantics, then the role requirement. The only minor redundancy is repeating the admin/write theme across the prefix, role statement, and WRITE label, but each sentence still 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 low-complexity admin write operation, the description covers the main action, the target domain, quantity semantics, and role requirement. An output schema exists, so return-value detail is not needed. It could mention overwrite behavior or restaurant scope more explicitly, but the essential context is present.

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 only 25%, so the description must compensate. It does explain the roles of menu_item_id and available_qty through 'menu item' and 'available quantity', but it does not clarify restaurant_id or the optional/required behavior beyond the schema. This is partial compensation, not complete 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 identifies the operation as setting the daily menu and clarifies the core semantics: assigning a menu item to a date with an available quantity. It is specific enough to be distinguished from menu-item CRUD siblings, though it does not explicitly name an alternative.

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

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

It gives clear practical guidance by marking the operation as ADMIN and WRITE, and it explicitly states the required roles (pac_cordinator or lunch_cordinator). It does not list when-not-to-use cases or alternatives, but the role and admin context help an agent decide when this tool applies.

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 labels the operation 'FINANCIAL + WRITE', going beyond the readOnlyHint=false annotation by explaining the real-world impact. The confirmation requirement is additional behavioral context not present in the annotations. It does not discuss side effects on existing orders, but that is a minor gap for a simple price-setting tool.

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

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

The description is a single compact sentence that front-loads the admin scope, then states the action, role requirement, and confirmation expectation with no wasted words. Every phrase adds 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 low-complexity, three-parameter tool with an output schema, the description covers the critical operational caveats: admin-only access, financial/write nature, and the need to confirm with the user. The main gap is the undocumented restaurant_id and menu_item_id semantics, though their roles are largely inferable from the parameter names and tool title.

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 only 33%, so the description needed to compensate by explaining restaurant_id and menu_item_id, but it does not. The only referenced concept is 'price,' which merely echoes the existing schema description for price_cents and adds no new parameter-level meaning.

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

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

The description starts with 'ADMIN' and states 'Sets the price of a menu item,' naming the specific verb and resource. This clearly distinguishes it from the sibling update_menu_item, which would handle broader menu-item edits rather than price changes specifically.

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

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

The description provides clear usage context by stating the required roles (pac_cordinator or lunch_cordinator) and instructing the agent to confirm the new price with the user before invoking. It does not explicitly name alternative tools or when-not-to-use conditions, 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?

The description explicitly warns that this is a WRITE operation and instructs the agent to confirm with the user before signing up. It also discloses idempotence, which goes beyond the readOnlyHint/destructiveHint annotations and adds meaningful behavioral context.

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

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

Three short sentences deliver the main action, required parameter source, and a critical side-effect warning with no filler. Every sentence earns its place and the most important caveat is clearly highlighted.

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 write operation, the description covers the core action, how to obtain the required ID, user confirmation, and idempotence. An output schema is present, so return-value detail is not needed. 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 only says shift_id is a 'Volunteer shift ID,' but the description adds provenance: the ID comes from get_upcoming_events or event detail. This gives the agent practical guidance on sourcing the parameter beyond the schema's minimal definition.

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: 'Signs up the authenticated user as a volunteer for a specific shift.' It clearly identifies the action and scope, and there is no close sibling tool with overlapping purpose. The mention of shift_id source further anchors what the tool does.

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

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

The description gives clear context for use by requiring shift_id from get_upcoming_events or event detail. It does not name alternatives, but none of the sibling tools compete with this volunteer signup action, so the guidance is effectively complete for routing.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false; the description adds that this is a WRITE operation, requires specific coordinator roles, and that user confirmation is needed. This is useful behavioral guidance beyond the structured fields, although it could mention side effects or reversibility.

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 clauses deliver purpose, access control, and confirmation guidance with no wasted words. The key verb and resource are front-loaded in the first phrase.

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

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

The role restriction and confirmation instruction cover important operational context, and an output schema exists. However, for a 10-parameter update operation with only 10% schema coverage, the description would benefit from stating that event_id plus optional fields can be supplied, and from noting the partial-update contract.

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 only 10% and the description provides no parameter-level guidance. It never explains that event_id is the required key, which other fields can be updated, or any format/constraints beyond the schema's bare property names.

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: 'Updates an existing school event.' This clearly distinguishes it from sibling creation tools like create_event and cancellation tools like cancel_event, so there is no ambiguity about what the operation does.

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

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

It sets clear context: this is an admin-only mutation for existing events and tells the agent to confirm changes with the user. It does not explicitly name alternatives or state when not to use it, but the 'existing' qualifier and sibling names make the usage boundary reasonably clear.

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

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

It discloses that this is a WRITE operation and lists required roles, which adds auth context beyond the annotations. However, it does not describe partial-update semantics, validation, or effects on menu availability, so the behavioral picture remains thin. No contradiction with the annotations because readOnlyHint=false aligns with WRITE.

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

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

The description is a single compact sentence with the key constraints front-loaded ('ADMIN', then the action, then roles and WRITE). Every clause earns its place and there is no flff.

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

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

Despite having an output schema and read/write annotations, the tool has 10 undocumented parameters and no use-vs-alternative guidance. The description provides the auth/write context but leaves too much for the agent to infer about which fields mean what and how an update behaves.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters, but it mentions none of the 10 fields. An agent cannot tell is_active from is_available or cost_cents from price_cents, and the required identifiers restaurant_id and menu_item_id are not contextualized.

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 ('Updates a menu item'), which clearly differentiates it from sibling tools such as create_menu_item, delete_menu_item, and set_menu_item_price. The ADMIN prefix further scopes the intended audience. This is enough for an agent to determine what the tool does.

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

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

The description provides clear context — it is an ADMIN write operation and requires pac_cordinator or lunch_cordinator — but it does not explicitly state when to prefer this over alternatives like set_menu_item_price or create_menu_item. Usage is implied rather than spelled out.

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