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?

The description goes well beyond the annotations by disclosing specific behavioral outcomes: refunding the wallet, rejection when labels are already sent, idempotency, and a strong destructive-operation warning requiring user confirmation. These details add meaningful context about side effects and state 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?

The description is compact and front-loaded with the core behavior, followed by important conditions and warnings. Each sentence serves a distinct purpose: action, side effect, destructive warning, rejection condition, and idempotency. No filler or redundant phrasing is present.

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

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

Given the simple one-parameter schema, existing annotations, and output schema, the description covers all the essential context an agent needs: when to call it, what will happen, what could reject it, and how to behave safely. The destructive nature is clearly stated, and the idempotency detail is valuable. 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?

The schema coverage is 100% and the single parameter order_id already has a clear description in the schema. The tool description restates the order context but adds no new parameter-level meaning beyond what the schema provides. This aligns with the baseline of 3 for fully covered schemas.

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 action: cancelling a finalized order, with a precise precondition (labels have not been sent yet). It also distinguishes itself from siblings like cancel_event by focusing on orders rather than events. This is a specific verb + resource definition that leaves no ambiguity about what the tool does.

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

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

The description clearly explains when the tool is applicable: only for finalized orders where labels have not yet been sent. It also warns about confirm-with-user behavior and states the rejection case. However, it does not explicitly name alternative tools such as cancel_event, so the when-not-to-use guidance is implicit rather than fully explicit.

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

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

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?

The description reveals key behavioral traits beyond annotations: deducting payment from a wallet, being a FINANCIAL + WRITE operation, requiring user confirmation, and being idempotent. These are valuable details not present in the annotations, which only show 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?

Three sentences, each earning its place: the action, the optional tip, and the critical financial confirmation warning with idempotency. The most important information is front-loaded and there is no wasted wording.

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

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

For a two-parameter financial write operation with an output schema present, the description covers the action, the optional tip, the financial risk, the confirmation requirement, and idempotency. Nothing essential is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds operational context around tip_cents ('donated to the school's PAC') but mostly repeats or reinforces what the schema already says. This meets the baseline for high schema coverage.

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

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

The description states a specific verb and resource: 'Finalizes a draft order, deducting payment from the wallet.' It clearly distinguishes this from siblings like cancel_order or create_draft_order by describing the finalization action and financial consequence.

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

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

The description clearly implies this should be called after creating a draft order and establishes a critical usage rule: 'always confirm with the user before calling.' It does not explicitly mention alternatives or when not to use it, but the financial/write warning and draft-order context provide strong situational 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 and destructiveHint, and the description reinforces this with 'Read-only.' It adds useful behavioral context beyond annotations: the active-school scoping, the either/or date-month behavior, and the fallback to today's menu. 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 short and front-loaded with the core purpose, followed by parameter behavior, safety, and intended use. The 'Read-only' sentence is somewhat redundant with the annotations, but every other sentence adds distinct value.

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

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

For a read-only tool with two optional string parameters and an output schema, the description is complete: it covers what is returned, which school context applies, how to specify date or month, the default behavior, and why an agent would call it. No significant missing information prevents correct invocation.

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

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

Schema coverage is 100%, so the parameter formats are already documented. The description adds important relational semantics: date and month are alternatives, both are optional, and omitting both defaults to today's menu. This goes beyond the individual property descriptions.

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

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

The description states a specific action and resource: it returns the daily lunch menu for the user's active school. It also explicitly connects the tool's purpose to finding menu_item_id values for order_lunch, which clearly distinguishes it from order placement and menu-listing siblings.

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

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

The description gives direct usage guidance: 'Use this to find menu_item_id values for order_lunch.' It also clarifies the default behavior when no date or month is provided. It does not explicitly name alternatives to avoid, but the intended context is clear enough for correct selection.

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

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

Annotations already 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 'Read-only' in the description adds no new safety information. It does add the aggregated 'summary' nature of the result, but provides no additional behavioral context such as scope limits or side effects. The student_id ownership constraint appears only in the schema, not in the description.

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

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

Two sentences with no filler; the primary function is front-loaded. 'Read-only' is slightly redundant with annotations but is a single harmless phrase. Overall structure is ideal for a simple read-only query.

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

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

Given the presence of both input and output schemas and annotations covering safety, the description covers the essentials: what is returned, how it can be filtered, and that it is read-only. A brief pointer distinguishing it from daily order tools would push it higher, but that is more of a usage-guideline concern.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description mentions filtering by month and student but adds no meaning beyond the schema, which already provides formats and the 'must be your own' constraint. No new syntactic or semantic guidance is offered.

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 a monthly summary of orders.' The word 'monthly' clearly distinguishes this tool from sibling get_daily_orders and get_orders. No ambiguity about what resource is acted on.

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

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

The description implies when to use it (when a monthly summary is needed) but gives no explicit exclusions or alternatives. An agent must infer from sibling names rather than being told, e.g., 'use get_daily_orders for daily data.'

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 destuctiveHint, and the description adds the own-students scope and recent time window as useful context. It restates 'Read-only' already captured by annotations and does not disclose ordering, pagination, or other response behavior; still, there is no contradiction.

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

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

The description is a single concise sentence, front-loads the core purpose and scope, and includes the optional parameter without extra fluff. Every clause is useful.

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-optional-param, read-only tool with an output schema and safety annotations, the description is nearly complete. The main gaps are lack of explicit sibling routing and the unspecified time boundary of 'recent', but neither blocks a competent call.

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

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

With 100% parameter schema coverage, the schema already defines student_id and that it must be the user's own. The description only says 'Optionally filter by student_id', which adds no meaning beyond the schema field description.

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

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

The description names a concrete verb and resource (returns recent lunch orders) and narrows scope to the authenticated user's students. The words 'recent' and 'students' help distinguish it from sibling tools like get_upcoming_orders or get_school_lunches, so an agent can see what this tool is for.

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 communicates the general context (recent orders for the user's own students) and an optional filter, but it does not explicitly say when to prefer this tool over sibling order/list tools. An agent would have to infer the temporal and ownership boundary from the wording.

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 behavior beyond the annotations by specifying that the result is scoped to the active school and that the filter is optional. The read-only hint is repeated, but the 'upcoming' temporal scope and active-school context are useful behavioral disclosures.

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

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

Two concise sentences cover the core purpose, scope, and optional parameters. The most important information is front-loaded, and there is no unnecessary elaboration.

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 nearly complete. It could clarify whether providing only one of start_date or end_date is valid, but that 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 coverage is 100%, and the description adds the relationship that start_date and end_date form an optional date range. It does not add much beyond the schema's format descriptions, but it clarifies the filtering intent.

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

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

The description states a specific action ('Returns upcoming events') and a clear resource scope ('the user's active school'), which separates it from sibling mutation tools like create_event and update_event. The optional date-range filter is also described precisely.

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 the read-only tool for upcoming events scoped to the active school. It does not explicitly list alternatives or when-not-to-use cases, but the read-only wording makes the choice versus mutation siblings obvious.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the return contents and emphasizing the required first-call behavior, which helps the agent understand the tool's role in the workflow. It 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?

Two sentences deliver maximum value: the first states the return data, the second provides an explicit ordering directive and confirms the read-only nature. Every sentence earns its place with no redundancy or filler.

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

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

For a zero-parameter read-only tool with an output schema, the description is fully complete. It covers the purpose, the data returned, the required call order, and the safety profile, leaving nothing an agent needs to infer before invoking it correctly.

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

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

The tool has zero parameters and the input schema is complete, so parameter semantics are trivially satisfied. The description correctly implies no input is needed, and with no parameters to document, baseline 4 is appropriate.

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

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

The description uses a specific verb 'Returns' and clearly identifies the resource: the authenticated Paxaver user context. It lists the exact contents (name, active school, guardian students, roles), leaving no ambiguity about what the tool provides, and it is distinct from all sibling tools.

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

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

The description explicitly states 'ALWAYS call this first before any other tool to establish context,' giving a clear and authoritative usage rule. Since no sibling tool provides user context, there is no alternative to distinguish against, and the sequencing guidance fully covers when to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which covers the safety profile. The description adds the 'Read-only' statement and the 'active school' scope, which provides some context beyond annotations. However, it does not disclose details like return format or possible edge cases (e.g., no active school), though the output schema likely covers the return structure. This is adequate but not exceptional.

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 filler. The main purpose is front-loaded in the first sentence, and the use case follows immediately. Every word contributes to clarity.

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 tool with an output schema, the description covers the critical aspects: what it returns, who it applies to (authenticated user), scope (active school), and when to use it. Nothing essential is missing for an agent to invoke it correctly.

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

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

The input schema has zero properties and schema description coverage is 100%, so there are no parameters to document. Per the rubric, baseline is 4 for zero-parameter tools. The description correctly adds no redundant parameter information.

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 current wallet balance for the authenticated user at their active school.' This clearly identifies what the tool does and its scope. However, it does not explicitly distinguish itself from sibling tools, though the sibling names mostly reflect different operations (orders, events, menus), so the differentiation is implicit.

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 a clear context for use: 'Use this to check funds before ordering lunch.' This tells the agent when the tool is relevant. It does not mention exclusions or alternative tools, but for a standalone read-only balance check with zero parameters, the guidance is sufficient.

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

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

Annotations already declare readOnly=true, destructive=false, and openWorld=false, so the safety profile is fully covered. The description's 'Read-only' merely restates the annotation and adds no behavioral context such as data freshness, authorization requirements, or side effects. It does disclose the return scope—balance, transactions, pending deposits—which gives modest extra context beyond the annotations.

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

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

Two short sentences with the core outcome front-loaded. The standalone fragment 'Read-only.' is redundant with the annotations and could be removed, but apart from that there is no wasted language. It is appropriately sized for a zero-parameter read tool.

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

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

For a zero-param, read-only tool with an output schema present, the description covers both the purpose and a usage cue. The only real gap is not mentioning get_wallet_balance as the lighter sibling for balance-only queries; an agent can still infer the distinction from the return contract, so the omission is minor.

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

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

The input schema is empty with zero parameters and schema description coverage is 100%, so there is no parameter documentation burden for the description to carry. A baseline of 4 for zero-param tools applies; no 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 names a precise resource—wallet status—and gives an explicit return contract: wallet balance plus recent transactions and pending deposits. The phrase 'wallet overview' positions it as a broader query than a bare balance check, distinguishing it from the get_wallet_balance sibling. Verb 'Returns' is concrete and unambiguous.

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

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

It gives an explicit use-case signal: 'Use this for a wallet overview.' This tells an agent when the tool is appropriate. It does not name get_wallet_balance as the lighter alternative or state when not to use it, stopping short of the explicit exclusion an ideal definition would include.

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.