Allows searching restaurants, browsing menus, building carts, inspecting checkout state, attaching payment, and placing orders. Also supports retrieval of campus card balances for USC/CarolinaCard when available.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@grubhub-mcp search for vegan restaurants near me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
an mcp server for grubhub. it can search restaurants, browse menus, build carts, inspect checkout state, attach payment, and place orders.
this also has campus dining helpers for usc/carolinacard. it can pull the same campus-card balances the grubhub mobile app shows, including meals, retail meals, meal plan dollars, and carolina cash when grubhub returns them.
python 3.11+ is required. dependencies: mcp, httpx, pydantic
python -m venv .venv
source .venv/bin/activate
pip install -e .
python -m grubhub_mcpon windows:
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .
python -m grubhub_mcpby default the server runs over stdio, which is what most local mcp clients want.
{
"mcpServers": {
"grubhub": {
"command": "/path/to/grubhub-mcp/.venv/bin/python",
"args": ["-m", "grubhub_mcp"]
}
}
}Related MCP server: FoodDash
MCP_TRANSPORT=stdio | http | streamable-http | sse
HOST=127.0.0.1
PORT=8001
MCP_PATH=/mcp
MCP_ALLOWED_HOSTS=comma,separated,hosts
MCP_ALLOWED_ORIGINS=comma,separated,origins
MCP_JSON_RESPONSE=1
GRUBHUB_SESSION_DIR=~/.grubhub-mcp
GRUBHUB_USER_AGENT="Grubhub/2026.24.2 (Android; Android 15)"GRUBHUB_SESSION_DIR is where login state is stored. keep that directory private.
the session file contains grubhub auth tokens.
this talks to grubhub's private/mobile api. some endpoints were mapped from the android app, including the campus-card balance call:
/tapingo/payments/{diner_udid}/campus-cards/v2/cards-balancesreverse engineering is EPIC!
add a new delivery address. (AUTH'D)
Args: street_address: Street address line city: City name state: State abbreviation (e.g. NY, CA) zip_code: ZIP code apt_suite: Apartment/suite number delivery_instructions: Special delivery instructions label: Label for the address (e.g. Home, Work)
| Name | Required | Description | Default |
|---|---|---|---|
| street_address | Yes | ||
| city | Yes | ||
| state | Yes | ||
| zip_code | Yes | ||
| apt_suite | No | ||
| delivery_instructions | No | ||
| label | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It only says 'add a new delivery address' and notes authentication, but does not disclose side effects, limits, or error states. This is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a clear list. It is front-loaded with the purpose and efficiently explains parameters without 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?
Although it covers purpose and parameters, it lacks information about output, error handling, and prerequisites (beyond authentication). With no annotations, it is moderate but incomplete.
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%, but the description includes a detailed Args section explaining each parameter (e.g., 'State abbreviation'). This adds meaningful context beyond schema titles.
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 'add a new delivery address', using a specific verb and resource. It also notes authentication requirement. This distinguishes it from sibling tools like get_addresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not specify when to use this tool versus alternatives (e.g., update_address not listed, but siblings include many unrelated tools). No when-not-to-use or alternative contexts provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
attach the linked campus card, such as CarolinaCard, to a cart.
Args: cart_id: The cart ID payment_id: Campus-card payment ID; default is campus_card amount_cents: Optional amount in cents; omit to cover remaining balance
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| payment_id | No | campus_card | |
| amount_cents | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does not disclose side effects (e.g., what happens if the card is not linked, whether existing payment is replaced), permissions required, or output format. The existence of an output schema is not addressed.
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 brief and organized with a header line and an Args block. Every sentence serves a purpose. Slight improvement could be removing the 'Args:' label since parameters are obvious, but it's not detrimental.
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, the description does not mention what the tool returns. There is no discussion of prerequisites (e.g., need for a linked campus card) or error conditions. For a 3-parameter mutation tool, this is insufficient.
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 0% schema coverage, the description adds crucial meaning: it explains 'cart_id' is the cart ID, 'payment_id' is the campus-card ID with default 'campus_card', and 'amount_cents' is optional with the note 'omit to cover remaining balance'. This substantially clarifies usage beyond the raw 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 explicitly states 'attach the linked campus card to a cart', with a specific example 'CarolinaCard'. This clearly distinguishes it from sibling 'add_payment_to_cart', which is generic. The verb 'attach' combined with the resource 'campus card' gives precise purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'add_payment_to_cart'. The description lacks explicit conditions, prerequisites, or exclusion scenarios. The agent has no help deciding between campus card and other payment methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add a restaurant to favorites. (AUTH'D)
Args: restaurant_id: The restaurant ID to favorite
| Name | Required | Description | Default |
|---|---|---|---|
| restaurant_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does not specify whether adding is idempotent, what happens if already favorited, or authentication requirements beyond a vague hint.
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?
Extremely concise with two sentences, front-loading the purpose and immediately describing the parameter. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity (1 param, output schema exists), the description omits crucial behavioral details and usage context, making it incomplete for reliable agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description adds minimal meaning: 'The restaurant ID to favorite'. This is helpful but basic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'add a restaurant to favorites', which distinguishes it from sibling tools like 'remove_favorite' and 'get_favorites'. However, it lacks a definition of what 'favorites' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, prerequisites, or context. The '(AUTH\'D)' hint is insufficient for clear usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
attach a saved payment method to a cart.
Args: cart_id: The cart ID payment_type: Grubhub payment type, such as CREDIT_CARD or CAMPUS_CARD payment_id: Payment method ID amount_cents: Optional amount in cents; omit to cover remaining balance
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| payment_type | Yes | ||
| payment_id | Yes | ||
| amount_cents | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It indicates mutation ('attach') but does not explain what happens on failure, side effects, or required state (e.g., cart must exist, payment method must be saved). This is insufficient for a mutation tool with no annotation support.
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 extremely concise: a one-sentence summary followed by a clean parameter list. Every sentence and element serves a purpose, 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?
Given the tool has 4 parameters, no annotations, and an output schema (not described), the description covers parameters well but lacks usage guidelines and behavioral context. It does not mention prerequisites or state changes, making it adequate but not fully complete for an AI agent.
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?
Despite 0% schema coverage, the description explains all four parameters with meaningful context. It provides example values for payment_type and clarifies that amount_cents is optional and defaults to covering the remaining balance. This adds significant value beyond the bare 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 uses the specific verb 'attach' and clearly identifies the resource as 'a saved payment method to a cart'. It provides examples of payment types (CREDIT_CARD, CAMPUS_CARD), distinguishing from sibling 'add_campus_card_payment' which likely handles a specific payment type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for attaching a saved payment method to a cart, but does not explicitly state when to use it versus alternatives like 'add_campus_card_payment', nor does it provide exclusion criteria or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add an item to an existing cart.
Args: cart_id: The cart ID to add to restaurant_id: The restaurant ID for the item menu_item_id: The menu item ID to add quantity: Number of this item (default 1) special_instructions: Special preparation instructions options: List of selected options/add-ons, each with {id, quantity}
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| restaurant_id | Yes | ||
| menu_item_id | Yes | ||
| quantity | No | ||
| special_instructions | No | ||
| options | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states the basic action but does not reveal side effects (e.g., whether duplicate items increment quantity, error conditions like mismatched restaurant_id, or if the cart must be in a certain state). Output schema exists but description lacks behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line summary followed by an Args list. Each parameter explanation is short and to the point. No unnecessary 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?
While the description explains parameters, it lacks contextual completeness for a mutation tool. It does not mention prerequisites (e.g., cart must exist, restaurant consistency) or what happens on conflict (e.g., item already in cart). Output schema may partially compensate, but the description should provide more usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides clear semantics for all 6 parameters, including the structure of the 'options' parameter (list of objects with id and quantity). This adds significant value beyond the schema's bare types and defaults.
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 'add an item to an existing cart,' specifying the action and the target resource. It distinguishes from sibling tools like create_cart (creates a new cart) and remove_from_cart (removes an item).
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 (adding items to an existing cart) but does not explicitly state when to use this tool versus alternatives like update_cart_item or when a cart must be created first. No guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply a gift card to a cart.
Args: cart_id: The cart ID card_number: Gift card number pin: Gift card PIN
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| card_number | Yes | ||
| pin | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the basic effect without disclosing potential errors, side effects (e.g., modifying cart total), or required permissions.
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 efficient with no wasted words, but it is too brief and lacks necessary detail, making it underinformative rather than concise.
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 3 required parameters, no annotations, 0% schema coverage, and similar sibling tools, the description fails to provide sufficient context about prerequisites, behavior, or error handling. An output schema exists but is not used to explain return values.
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 description lists parameters with minimal labels (e.g., 'The cart ID'), but adds no meaning beyond the parameter names. With 0% schema description coverage, this fails 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?
The description clearly states the action (apply) and resource (gift card to a cart), but does not differentiate from the sibling tool 'apply_promo_code', which serves a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as 'apply_promo_code'. No prerequisites or contextual conditions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
apply a promotion code to the cart.
Args: cart_id: The cart ID promo_code: The promotion code to apply
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| promo_code | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavior. It does not mention side effects (e.g., modifies cart total), idempotency, error conditions, or whether it is read-only. The mutation nature is implied but not explicit.
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 main action. It includes a structured 'Args' section, with no wasted words. However, it could be more comprehensive without losing conciseness.
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 an output schema, it is acceptable to skip return value details. However, the description lacks context about validation, constraints, or error handling, which would be useful for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by providing brief but clear definitions for both parameters: 'cart_id: The cart ID' and 'promo_code: The promotion code to apply'. This adds meaning beyond the schema's empty 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 clearly states 'apply a promotion code to the cart', with a specific verb and resource. It distinguishes from sibling 'apply_gift_card' by specifying 'promo code' versus gift card, but lacks explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'apply_gift_card'. There are no prerequisites, restrictions, or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get autocomplete suggestions for a search query.
Args: query: The partial search text latitude: Latitude for location context longitude: Longitude for location context location_mode: DELIVERY or PICKUP (default DELIVERY)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| latitude | Yes | ||
| longitude | Yes | ||
| location_mode | No | DELIVERY |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only describes inputs and does not mention rate limits, result behavior, side effects, or whether it is read-only. For a tool with no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. It uses a clear arg list format. It earns its sentences but could include more detail without increasing length significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and an output schema exists (context signal), the description does not need to explain return values. However, it lacks important context such as constraints on coordinates, maximum query length, or the fact that latitude/longitude are required. The description minimally covers completeness, but gaps remain.
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 compensate. It adds minimal meaning: 'query' is described as 'partial search text,' latitude/longitude as 'for location context,' and location_mode has a default. However, it provides no additional constraints, formats, or examples, and repeats schema information without significant enrichment.
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 'get autocomplete suggestions for a search query,' identifying the specific verb and resource. This distinguishes it from sibling tools like search_restaurants and search_campus_restaurants, which perform full searches rather than autocomplete.
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 lists arguments and implies usage for partial search queries, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., full search tools). There is no mention of when not to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
change account password. (AUTH'D)
Args: current_password: Current password new_password: New password
| Name | Required | Description | Default |
|---|---|---|---|
| current_password | Yes | ||
| new_password | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It states the tool changes the password but does not mention side effects (e.g., session invalidation, re-login requirements, or idempotency). The behavioral impact is largely opaque.
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 extremely concise—one sentence plus a parameter list. It is efficient with no wasted words, though it could be slightly expanded to include useful behavioral notes without losing brevity.
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 omits critical contextual information for a password-changing tool, such as whether the operation requires the current password verification (implied but not stated), what happens after success (e.g., logout), or any error conditions. The presence of an output schema (not shown) reduces the need to describe return values, but the overall completeness is low.
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 0% description coverage, so the description must compensate. It provides basic explanations for both parameters ('Current password', 'New password'), which clarifies their roles but lacks details on constraints like length or composition rules.
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 'change account password', which is a specific verb+resource combination. It distinguishes itself from sibling tools like 'login', 'logout', and 'send_password_reset', making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only includes '(AUTH'D)' to indicate authentication is required, but provides no explicit guidance on when to use this tool versus alternatives such as 'send_password_reset' for forgotten passwords. No usage context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Grubhub account.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| password | Yes | ||
| first_name | Yes | ||
| last_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description fails to disclose side effects (e.g., auto-login, verification email), error states, or idempotency, which is critical for a mutation 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?
Single sentence is concise but underspecified for the complexity of account creation; it should include more context without excessive verbosity.
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 no annotations and no description of return values or behavior, the description is incomplete for a tool that creates sensitive resources.
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 0%; description mentions no parameters and adds no meaning beyond the schema, which is insufficient for a 4-parameter tool with no enums.
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' and the resource 'new Grubhub account', distinguishing it from sibling tools like 'login' and 'logout'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites (e.g., user not logged in), and no conditions like email uniqueness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create a new cart with the first item.
Args: restaurant_id: The restaurant ID to order from menu_item_id: The menu item ID to add quantity: Number of this item (default 1) special_instructions: Special preparation instructions options: List of selected options/add-ons, each with {id, quantity} latitude: Delivery latitude longitude: Delivery longitude is_delivery: True for delivery, False for pickup
| Name | Required | Description | Default |
|---|---|---|---|
| restaurant_id | Yes | ||
| menu_item_id | Yes | ||
| quantity | No | ||
| special_instructions | No | ||
| options | No | ||
| latitude | No | ||
| longitude | No | ||
| is_delivery | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'create a new cart' without describing side effects (e.g., does it overwrite an existing cart?), auth requirements, or return behavior. The parameter list does not reveal behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose, followed by a structured Args list. It is efficient given 8 parameters, though some explanations could be more concise. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 params, no annotations) and presence of output schema, the description covers parameter semantics but lacks context about prerequisites (e.g., login required), behavior on duplicate cart, and error scenarios. Basic but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaningful explanations for each parameter (e.g., 'options' format, 'restaurant_id' as 'the restaurant ID to order from'), going beyond the schema's titles and types. Missing constraints like value ranges or formats for some 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 'create a new cart with the first item', using a specific verb and resource, and the parameter list reinforces the purpose. It distinguishes the tool from sibling 'add_to_cart' implicitly by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'add_to_cart' or 'update_cart_item'. Missing context about whether a new cart should be created only when no cart exists, or if it overwrites existing ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
estimate whether a USC retail meal swipe is a good payment choice.
Args: cart_total_cents: Cart total in cents from get_cart_payment_options meal_period: breakfast, lunch, dinner, or late_night swipes_remaining: optional known remaining retail swipes meal_plan_dollars_cents: optional known Meal Plan Dollars balance carolina_cash_cents: optional known CarolinaCash balance
| Name | Required | Description | Default |
|---|---|---|---|
| cart_total_cents | Yes | ||
| meal_period | Yes | ||
| swipes_remaining | No | ||
| meal_plan_dollars_cents | No | ||
| carolina_cash_cents | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states the estimation behavior and lists input parameters, but does not describe the output format or side effects. Basic behavior is clear, but lacks detail on return value (though output schema exists).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a single-line purpose, followed by a concise 'Args' list. No extra fluff, though the argument descriptions could be more integrated. Efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not explain return values in detail. However, it lacks context on limitations (e.g., what constitutes 'good'), assumptions, or usage constraints. Leaves several questions unanswered for an AI agent.
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 0%, so description must add meaning. The 'Args' section explains each parameter briefly (e.g., meal_period values, optional fields). This adds value beyond the bare schema, but could be more precise (e.g., source for optional params).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'estimate whether a USC retail meal swipe is a good payment choice.' It uses a specific verb and resource, and this function is distinct from all sibling tools (no other estimation tool).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when deciding payment options for a cart and references a related tool (get_cart_payment_options), but does not explicitly state when to use this vs alternatives or mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get saved delivery addresses. (AUTH'D)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates authentication is required via '(AUTH'D)', which is a behavioral trait. However, it does not disclose idempotency, pagination, or behavior when no addresses exist. Since no annotations are present, the description carries the full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose without any wasted words. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description is minimally adequate. However, it lacks context about what 'saved delivery addresses' refers to (e.g., user-specific) and when to use it over other get tools. It is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is trivially 100%. The description adds no additional parameter details, but none are needed. Baseline 4 for 0 parameters 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 action ('get') and the resource ('saved delivery addresses'), and the '(AUTH'D)' suffix provides authentication context. It is specific and distinguishes itself from sibling tools like 'add_address'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as 'get_order_history' or 'get_profile'. It does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get live CarolinaCard/campus-card balances from Grubhub.
Args: cart_id: Optional cart ID for checkout-context tender eligibility restaurant_id: Optional restaurant ID for checkout-context tender eligibility selected_payment_id: Optional selected campus tender/payment ID include_raw: Include Grubhub's raw campus-card balance response
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | No | ||
| restaurant_id | No | ||
| selected_payment_id | No | ||
| include_raw | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the tool gets 'live' balances, implying a read-only, real-time operation, but does not elaborate on authentication requirements, rate limits, or any side effects. The mention of 'include_raw' hints at optional behavior, but overall transparency is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with the main purpose in a single sentence, followed by a clear parameter list. No redundant information is present, and all sentences serve a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description does not need to detail return values. However, it omits important context such as whether authentication is required, error handling, or when optional parameters are necessary. The tool's simplicity and four optional parameters make the description adequate but not comprehensive.
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 0% schema description coverage, the description compensates by providing brief but meaningful explanations for all four parameters (cart_id, restaurant_id, selected_payment_id, include_raw). These add context beyond the schema, such as 'checkout-context tender eligibility'. While not exhaustive, they are sufficient for basic understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves live CarolinaCard/campus-card balances from Grubhub, using a specific verb ('get') and a distinct resource. This differentiates it from siblings like 'get_gift_card_balance' and 'get_payment_methods'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description is purely functional, lacking context about prerequisites, typical scenarios, or exclusions that would help an agent decide between this and similar balance-checking tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get the current state of a cart including items, totals, and fees.
Args: cart_id: The cart ID
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description indicates a read operation (get state) but does not disclose idempotency, side effects, or auth requirements. It minimally conveys non-destructive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear purpose sentence followed by a parameter list. It is well-structured and front-loaded, though the parameter list is redundant with the schema.
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, important context is missing: cart scope (user-specific?), permissions required, or whether it returns the same as get_cart_bill. The description is insufficient for an agent to fully understand usage.
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 0%. The description merely repeats 'The cart ID' from the schema without adding any additional meaning, such as format, source, or constraints. No value added beyond structured data.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the current state of a cart including items, totals, and fees. This distinguishes it from sibling tools like create_cart, add_to_cart, or get_cart_bill.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It only implies usage by stating what it does, but does not mention when not to use it or provide alternative tool names for specific needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get the calculated bill for a cart, including checkout validation.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral transparency. It mentions 'checkout validation' but does not explain what that entails, whether it modifies state, or any prerequisite calls (e.g., cart must exist). This leave gaps about side effects and authority.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the main purpose. It is concise, but could be slightly more informative without losing brevity.
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, the description does not need to detail return values. However, given the tool's simplicity (1 parameter), the description covers the basic purpose but lacks usage guidance and behavioral details, making it adequate but not comprehensive.
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 'cart_id' has no description in the schema (0% coverage) and the tool description does not add any meaning, such as how to obtain the cart_id or its expected format. The description does little to clarify the parameter beyond its name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and the resource 'calculated bill for a cart', and highlights 'including checkout validation', which distinguishes it from related tools like 'get_cart' or 'place_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 implies usage when you need the bill before checkout, but it does not explicitly state when to use this tool versus alternatives, nor does it provide any conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get cart-scoped payment options, including campus-card availability.
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only adds 'including campus-card availability' beyond the name. Does not disclose whether it requires authentication, modifies state, or any other behavioral traits. With no annotations, the burden is on the description, which is minimal.
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?
Single sentence is concise, but it under-specifies the tool. It is not verbose, yet fails to provide enough detail. Earns a neutral score.
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 an output schema, return values are covered. However, the tool has one parameter with no description, no usage guidelines, and minimal behavioral info. Incomplete for an agent to use 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 0%. The only parameter, cart_id, is not explained in the description. No hint about format or how to obtain it. The description adds no 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?
Description clearly states it retrieves cart-scoped payment options and specifically mentions campus-card availability. The verb 'get' and resource 'cart-scoped payment options' are specific. However, it does not explicitly differentiate from siblings like get_payment_methods, which might be user-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?
No guidance on when to use this tool versus alternatives such as add_payment_to_cart or get_payment_methods. No context about prerequisites or typical use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get favorite/saved restaurants. (AUTH'D)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It only states it retrieves favorites with no details on return format, pagination, or authentication requirements (only implied). Fails to add 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?
Single sentence is efficient and front-loaded. However, it could include more key information without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is reasonably complete. However, it lacks explicit statement that it returns a list of restaurants and could mention any ordering or filtering. Adequate but not thorough.
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?
Tool has zero parameters and schema description coverage is 100%, so baseline is 4. Description adds no parameter info, which is acceptable as there are none to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and resource 'favorite/saved restaurants', immediately conveying the tool's purpose. It distinguishes from sibling tools like 'add_favorite' and 'remove_favorite'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'get_order_history' or 'get_profile'. The only hint is '(AUTH'D)', implying authentication is required, but no explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check the balance of a Grubhub gift card.
Args: card_number: Gift card number pin: Gift card PIN
| Name | Required | Description | Default |
|---|---|---|---|
| card_number | Yes | ||
| pin | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'check balance' without disclosing safety profile (read-only), authentication needs, or side effects. Minimal transparency for a tool that likely has no destructive effects.
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 extremely concise, front-loading the purpose in the first sentence, and efficiently listing arguments in a clear format without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple balance-check tool with an output schema, the description is nearly complete. It could mention that checking balance is typically a prerequisite for apply_gift_card, but the core functionality is well covered.
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%, but the description adds 'Gift card number' and 'Gift card PIN' for the two parameters, adding basic meaning beyond names. However, it does not specify format, length, or other constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks the balance of a Grubhub gift card, using specific verb 'check' and resource 'balance of a Grubhub gift card'. It distinguishes from sibling tools like apply_gift_card and get_campus_card_balances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when checking gift card balance but lacks explicit guidance on when to use versus alternatives, no when-not-to-use scenarios, and no context about prerequisites or ordering relative to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get details for a specific order.
Args: order_id: The order ID
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only says 'get details' with no mention of side effects, authentication, rate limits, or response structure. The output schema exists but description adds no 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?
Very short and front-loaded, but under-specified. The two-line description is efficient but omits important details that an agent would need.
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 it has an output schema, the need for return description is lower. However, no usage context, no example, and no distinction from similar tools. For a simple tool, more context would help.
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 0%, meaning the description does not explain parameters beyond the schema. The docstring 'order_id: The order ID' adds no value over the schema's title 'Order Id'.
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 it gets details for a specific order (verb+resource). However, it does not distinguish from sibling tools like track_order or get_order_history, which could have similar purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description lacks context like prerequisites, typical use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get past order history. (AUTH'D)
Args: page_size: Number of orders per page (default 10) page_num: Page number (default 0)
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | ||
| page_num | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It only states 'get past order history'—a read operation—without disclosing behavioral traits such as pagination limits, ordering, or data freshness. More detail is needed for a mutation-free 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 extremely concise: a brief purpose line followed by a structured argument list. Every sentence serves a purpose 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?
An output schema exists, so return values need not be explained. However, the description lacks context on pagination behavior, result ordering (e.g., most recent first), and whether it returns full order details or summaries. Given the simplicity, this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description explains both parameters: page_size (number of orders per page) and page_num (page number), including defaults. This adds useful semantic meaning beyond the schema's titles and defaults.
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 clear verb+resource pattern ('get past order history'), indicating the tool retrieves historical orders. It distinguishes from siblings like 'get_order' (single order) and 'track_order' (current order status), but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions authentication requirement ('AUTH\'D') and default pagination values, offering minimal guidance. It does not specify when to use this over alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get the recommended Grubhub ordering workflow and safety rules.
call this before building an order, especially for campus-card orders.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must convey behavioral traits. It implies a read-only operation (getting information) but doesn't explicitly state it's non-destructive or detail side effects. Adequate for a guide 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?
Two concise sentences: first states the purpose, second provides usage context. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the existence of an output schema, the description sufficiently explains the tool's role. It mentions workflow and safety rules, which is appropriate for a guide.
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?
No parameters exist in the schema (coverage 100%), but the description adds meaning by explaining the content (workflow and safety rules). Adds value beyond the empty 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 clearly states the tool retrieves the 'recommended ordering workflow and safety rules,' specifying a unique resource not covered by sibling tools like create_cart or place_order. The action verb 'get' and resource 'ordering guide' are distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises calling the tool 'before building an order' and highlights importance for 'campus-card orders.' While it doesn't mention alternatives, the guidance is actionable and context-specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get account-level saved payment methods. (AUTH'D)
campus cards are cart-scoped on Grubhub. use get_cart_payment_options after creating a cart to see whether CAMPUS_CARD is available.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the scope (account-level, not cart-scoped) and includes the authentication hint. However, it does not specify behavior for edge cases (e.g., no payment methods) or error conditions, which would improve transparency.
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 concise: two short sentences with no filler. It front-loads the main purpose and immediately follows with a critical usage distinction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and low complexity, the description sufficiently covers its purpose and context. It mentions authentication and clarifies the relationship with the sibling tool. An output schema exists, so return values are not required.
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 no parameters and schema coverage is 100%, so baseline is 4. The description does not need to add parameter info.
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 'get account-level saved payment methods' specifying the verb and resource. It distinguishes from sibling tools by noting that campus cards are handled by get_cart_payment_options, avoiding confusion.
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 tells when to use the alternative: 'use get_cart_payment_options after creating a cart to see whether CAMPUS_CARD is available.' It also signals authentication requirement with '(AUTH\'D)'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get the current user's profile information (AUTH'D)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states it gets profile info and requires auth. Does not disclose return format, field details, or side effects. With output schema present, more detail could be added, but it's not contradictory.
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?
Single sentence, efficient and front-loaded. Could be slightly more informative, but 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?
Given no parameters and an output schema, the description is adequate. With many sibling tools, more context could help, but the name and description are clear enough.
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?
No parameters exist, so schema coverage is 100%. Description does not need to add parameter meaning, achieving baseline 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'get', resource 'current user's profile information', and context '(AUTH'D)'. Differentiates from siblings like get_session_info or get_addresses.
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 'AUTH'D' tag indicates required authentication, guiding appropriate use. No explicit exclusions or alternatives, but context is sufficient for a simple profile retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get restaurant details including menu, hours, ratings, and delivery info.
Args: restaurant_id: The Grubhub restaurant ID latitude: Optional latitude for delivery estimates longitude: Optional longitude for delivery estimates order_type: Order type - standard, catering (default standard)
| Name | Required | Description | Default |
|---|---|---|---|
| restaurant_id | Yes | ||
| latitude | No | ||
| longitude | No | ||
| order_type | No | standard |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It lists what is returned but does not mention side effects, permissions, or confirm it is read-only. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear one-line purpose followed by parameter list. No superfluous content. Could be slightly more structured with headings.
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 there is an output schema, the description adequately covers return types (menu, hours, ratings, delivery info). No missing critical context like rate limits or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are missing (0% coverage), but the tool description provides meaningful explanations for all parameters, including the purpose of latitude/longitude for delivery estimates and default order_type.
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 it retrieves restaurant details including menu, hours, ratings, and delivery info, distinguishing it from sibling tools like get_menu, get_menu_item, or search_restaurants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. While the description implies it covers comprehensive details, it does not mention when not to use it or provide context about sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current authentication state and session info.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description only states what it gets. It does not disclose read-only nature, required auth status, or potential side effects, but the name and context suggest non-destructive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One clear sentence, no extraneous words. Front-loaded with key action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is vague about what 'authentication state' and 'session info' include; could specify fields like logged-in status, user ID, or token validity for better completeness.
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?
No parameters, so schema coverage is 100%; description does not need to add param info. Baseline score of 4 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 clearly states the tool retrieves authentication state and session info, effectively distinguishing it from sibling tools that perform actions (e.g., login, logout) or manage other resources.
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 use for checking current authentication, but does not explicitly state when to use it versus alternatives or provide scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get USC CarolinaCard meal-swipe rules used by optimizer tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the tool's purpose without disclosing any behavioral traits (e.g., read-only, no side effects, expected behavior). The one-sentence description is insufficient for transparency.
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 clear sentence with no fluff, earning its place. It is front-loaded with the purpose. However, it could be expanded slightly without losing conciseness to improve completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists but the description does not summarize what the rules contain, and the tool has many siblings, the description is too sparse. It fails to provide enough context for an AI agent to understand when to use this tool vs others like get_campus_card_balances.
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 with 100% schema coverage, so the description does not need to add parameter details. Baseline 4 is appropriate as there is nothing to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets 'USC CarolinaCard meal-swipe rules' and mentions usage by 'optimizer tools,' which distinguishes it from sibling tools like estimate_usc_retail_swipe_value. However, it does not explicitly contrast with other get tools, missing full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The phrase 'used by optimizer tools' implies a specific context but does not provide explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log in to Grubhub with email and password. Returns session info on success.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| password | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions returning session info but omits critical details such as side effects (e.g., invalidating previous sessions), rate limits, security implications, or what happens on failure. The lack of transparency is a significant gap.
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, clear sentence that is front-loaded with the core action. It could be more structured (e.g., bulleted output info) but is concise overall.
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 existence of an output schema (implied but not provided), the description still lacks completeness. It does not cover failure modes, error messages, session duration, or security context. For a critical authentication tool, this is insufficient.
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%, meaning the schema provides no descriptions beyond titles and types. The description adds minimal value by repeating 'email and password' but offers no additional constraints, formats, or semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: logging in to Grubhub with email and password, and specifies that it returns session info on success. It distinguishes itself from sibling tools like send_login_otp and verify_login_otp, which handle OTP-based authentication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives (e.g., OTP-based login). It does not mention prerequisites, error handling, or scenarios where login might fail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log out of the current Grubhub session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose all behavioral traits. It only states the action ('Log out') without mentioning side effects (e.g., token invalidation, cart clearing) or prerequisites (e.g., being logged in). This is insufficient for a mutation 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 sentence with no wasted words. However, it omits potentially useful behavioral details, balancing conciseness against completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless tool, the description is minimally adequate. However, it does not explain the return value or confirm success, even though an output schema exists. It lacks context about when the session is considered active.
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?
No parameters exist; schema coverage is 100%. The description correctly implies no arguments are needed, adding no extra information but also not missing anything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Log out') and the resource ('current Grubhub session'), making it distinct from sibling tools like 'login' or 'create_account'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., ending a session vs. checking session info). The straightforward nature of logout partially mitigates this, but it remains a gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
place an order from a cart. (AUTH'D)
Args: cart_id: The cart ID to submit as an order payment_method_id: Optional payment method ID to attach before checkout payment_type: Payment type for payment_method_id, such as CREDIT_CARD or CAMPUS_CARD tip_amount: Optional tip amount in dollars
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| payment_method_id | No | ||
| payment_type | No | CREDIT_CARD | |
| tip_amount | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must carry the full burden of behavioral disclosure. It only states the action and parameters, but omits side effects (e.g., cart becomes inactive), success/failure responses, or idempotency. The '(AUTH'D)' marker is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but uses an 'Args' block that is somewhat informal. It front-loads the purpose and lists parameters efficiently. Minor improvement could integrate parameter docs more seamlessly.
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 4 parameters and an output schema, the description covers parameter semantics but lacks usage context (e.g., prerequisites, error scenarios). The tool's complexity warrants more guidance on when and how to use it, which is absent.
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 0%, so the description compensates by explaining each parameter: cart_id (mandatory), payment_method_id (optional), payment_type (with examples), and tip_amount (optional). This adds meaning beyond the schema's titles and types, though defaults and constraints could be clearer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'place an order from a cart.' It uses a specific verb ('place') and resource ('order from a cart'), which distinguishes it from sibling tools like 'add_to_cart' or 'get_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 provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites like having a valid cart, being logged in, or the need for payment method. The '(AUTH'D)' hint is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add or update the tip after delivery.
Args: order_id: The order ID tip_amount: Tip amount in dollars
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | ||
| tip_amount | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states 'add or update' without mentioning idempotency, side effects, authentication needs, or other safety details. This is insufficient for a mutation 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 short and includes a structured Args section. It is clear without unnecessary words, though it could be slightly more concise by combining lines.
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 basic operation but lacks details on return values or error conditions, even though an output schema exists. For a simple tool, it is adequate but could provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds brief parameter explanations: 'order_id: The order ID' and 'tip_amount: Tip amount in dollars.' The unit clarification ('in dollars') is helpful, but the descriptions are minimal.
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 'add or update the tip after delivery,' specifying the resource (tip), action (add/update), and context (after delivery). It distinguishes from siblings like 'set_tip' by implication, but does not explicitly contrast.
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 indicates when to use ('after delivery'), but provides no exclusions or explicit guidance on when not to use it, nor does it reference alternatives like 'set_tip' for pre-delivery tips.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
remove a restaurant from favorites. (AUTH'D)
Args: restaurant_id: The restaurant ID to unfavorite
| Name | Required | Description | Default |
|---|---|---|---|
| restaurant_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states authentication requirement but omits idempotency, error handling, or side effects.
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?
Extremely concise with no wasted text. Front-loaded with purpose and auth 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?
Has output schema, so return values need not be described. However, lacks behavioral context like idempotency or error behavior for a simple removal 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?
Parameter description merely restates the schema field name ('restaurant ID to unfavorite') without adding format, source, or constraints. Schema coverage 0% magnifies the gap.
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?
Clear verb ('remove') and resource ('restaurant from favorites') are stated. Distinguishes from sibling add_favorite.
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?
Briefly notes AUTH'D, but no explicit when-to-use or alternatives. Context suggests it complements add_favorite, but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
remove an item from the cart.
Args: cart_id: The cart ID line_item_id: The line item ID to remove
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| line_item_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives no behavioral details beyond 'remove'. It does not disclose side effects (e.g., cart total update), irreversibility, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, with no unnecessary words. However, it sacrifices completeness for brevity.
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 (not shown), the description lacks any mention of return values or post-conditions. For a simple 2-parameter tool, it fails to provide sufficient context beyond the basic action.
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 parameter descriptions add minimal meaning: 'The cart ID' and 'The line item ID to remove'. This is basic but necessary clarification.
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 'remove an item from the cart', specifying the verb (remove) and resource (item from cart), which distinguishes it from sibling tools like add_to_cart and update_cart_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., update_cart_item). There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create a new cart from a previous order for easy reordering.
Args: order_id: The order ID to reorder
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full weight. It states that a new cart is created, but it does not disclose whether the existing cart is replaced or if the action is idempotent, what happens to the original order, or any required permissions. This lack of detail is risky for a mutation 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 very short (one sentence plus parameter comment), which is efficient. However, it may be too brief given the lack of annotations, but it avoids unnecessary 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 tool is simple with one parameter and an output schema exists, so the description covers the basic functionality. However, it misses important context like prerequisites (e.g., order must belong to user), side effects (new cart replaces current?), and error conditions.
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 description adds basic meaning to the order_id parameter ('The order ID to reorder'), but does not specify format, source, or constraints. With 0% schema description coverage, this minimal addition is acceptable but not rich.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new cart from a previous order, which distinguishes it from sibling tools like create_cart (empty cart) and add_to_cart (adds to existing cart). The verb 'reorder' and resource 'cart from order' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when wanting to reorder from a past order, but it does not explicitly state when not to use it or mention alternatives. For example, it doesn't compare to using add_to_cart with items from an order manually.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search Grubhub campus/onsite restaurants near a campus location.
use this for campus-card dining. it sets Grubhub locationMode=CAMPUS.
Args: latitude: Latitude of the campus pickup/delivery location longitude: Longitude of the campus pickup/delivery location query: Optional restaurant or dish query page_size: Number of results per page (default 20) page_num: Page number for pagination (1-based, default 1)
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | Yes | ||
| longitude | Yes | ||
| query | No | ||
| page_size | No | ||
| page_num | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool sets Grubhub locationMode=CAMPUS, which is a key behavior. However, it does not mention authentication requirements, error handling, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two introductory lines and a clear parameter list. It is front-loaded with purpose and usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with an output schema, the description covers purpose, usage, and parameters adequately. However, it omits details such as authentication requirements and what happens with no results.
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 description adds explanations for all 5 parameters beyond the empty schema, including context for latitude/longitude and default values for page_size/page_num. However, the explanations are minimal and do not provide additional constraints or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Grubhub campus/onsite restaurants near a campus location, specifies it is for campus-card dining, and distinguishes from the sibling tool search_restaurants by noting it sets locationMode=CAMPUS.
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 says 'use this for campus-card dining', providing clear context for when to use. However, it does not explicitly state when not to use or mention alternatives beyond the implied sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search for restaurants near a location.
Args: latitude: Latitude of the delivery address longitude: Longitude of the delivery address query: Optional search query (cuisine, restaurant name, dish) page_size: Number of results per page (default 20) page_num: Page number for pagination (1-based, default 1) sort_type: Optional sort; leave empty for default relevance location_mode: DELIVERY, PICKUP, CAMPUS, ONSITE, or PICKUP_CAMPUS (default DELIVERY)
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | Yes | ||
| longitude | Yes | ||
| query | No | ||
| page_size | No | ||
| page_num | No | ||
| sort_type | No | ||
| location_mode | No | DELIVERY |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It describes parameters and defaults but fails to mention key behaviors: that it is a read-only search, what happens with no results, pagination behavior beyond defaults, or any rate limits or prerequisites. The absence of such details limits transparency.
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 efficient: a one-line purpose statement followed by a clean list of arguments with explanations. No redundant information. The structure is front-loaded 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?
Given 7 parameters and 0% schema coverage, the description adequately explains inputs, defaults, and pagination. An output schema exists, so return details are not required. However, missing information on error handling, empty results, or authentication context slightly reduces completeness.
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 compensate. It does so by providing clear explanations for each parameter, including the meaning of latitude/longitude (delivery address), query examples, valid location_mode values, and defaults. This adds substantial value beyond the schema titles, making parameters well-understood.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for restaurants near a location, specifying the verb and resource. However, it does not explicitly differentiate from sibling tool 'search_campus_restaurants', which may also search for restaurants but in a campus context. The inclusion of location_mode with CAMPUS option provides some differentiation, but not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives (e.g., 'search_campus_restaurants'), nor does it mention when not to use it. It simply states what the tool does, leaving the agent to infer usage context from the parameter options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a one-time passcode to the given email for login.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose important behavioral details such as side effects, rate limits, OTP validity, or whether it invalidates previous codes. The description only states the action without transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, efficiently communicating the core action without extraneous information. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description covers the basic action but lacks details about context such as typical usage flow, expected response, or preconditions. It is adequate but not thorough.
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 adds no additional meaning to the 'email' parameter beyond what the schema already provides. For a single, obvious parameter, this is minimally acceptable but does not compensate for the lack of coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends a one-time passcode to an email for login, distinguishing it from sibling tools like verify_login_otp and send_password_reset. The verb 'send' and resource 'one-time passcode' specify the action and object.
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 context ('for login') but does not explicitly state when to use this tool versus alternatives like verify_login_otp or login. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a password reset OTP to the given email.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only says 'send'. It lacks critical behavioral details: whether the email is validated, if the OTP is rate-limited, expiration, or error handling (e.g., silent failure for non-existent email).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. However, it could be slightly more structured with bullet points for clarity, but overall it is appropriately concise.
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 security-sensitive nature (password reset), the description lacks critical context: OTP expiration, visibility of success/failure to avoid user enumeration, rate limiting, or links to authentication docs. Output schema exists but description does not reference it.
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 sole parameter 'email' has 0% schema description coverage. The description adds no additional meaning (e.g., format, registered email requirement) beyond the parameter name.
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 it sends a password reset OTP to an email, differentiating from send_login_otp which is for login. However, it does not explicitly distinguish itself from sibling tools like change_password or verify_login_otp.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as change_password or verify_login_otp. It does not mention prerequisites (e.g., user must exist) or context of use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mark a cart for delivery with coordinates before full address is set.
Args: cart_id: The cart ID latitude: Delivery latitude longitude: Delivery longitude
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| latitude | Yes | ||
| longitude | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether the tool replaces existing location, its reversibility, or error conditions (e.g., if full address already set).
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 main purpose, followed by parameter list. Every sentence adds value, though the argument descriptions could be integrated more concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 required parameters) and presence of an output schema, the description covers the basic action but omits important context about side effects, prerequisites, and error handling.
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 0% schema description coverage, the description adds minimal context beyond the schema titles: 'cart ID', 'Delivery latitude', 'Delivery longitude'. It explains the purpose of the coordinates but lacks constraints like range or format.
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 'mark a cart for delivery with coordinates' and specifies the resource (cart with incomplete delivery location). It distinguishes from siblings like 'set_pickup_info' and 'add_address' by focusing on coordinates before full address.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when only coordinates are available ('before full address is set') but does not explicitly state when to use or avoid this tool, nor provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set pickup contact information on a cart before checkout.
Args: cart_id: The cart ID name: Pickup contact name phone: Pickup contact phone number email: Pickup contact email address pickup_instructions: Optional pickup instructions
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| name | Yes | ||
| phone | Yes | ||
| Yes | |||
| pickup_instructions | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral transparency. It does not disclose side effects (e.g., overwriting existing pickup info), permissions, validation, or idempotency—important for a mutation 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 brief and includes a structured list, but the parameter descriptions are somewhat redundant with the schema; could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists (mitigating need for return value details), but the description lacks context on behavior like overwrite rules, error conditions, or the impact on cart checkout flow.
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 0%, yet the description merely restates parameter names and basic purposes (e.g., 'The cart ID'), adding little meaning beyond the schema. Could include constraints, formats, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (set) and the resource (pickup contact information on a cart) and provides context (before checkout), differentiating it from sibling tools like add_address or update_cart_item.
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 before checkout but does not provide explicit guidance on when to use this tool vs. alternatives, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
set the tip amount on the cart.
Args: cart_id: The cart ID tip_amount: Tip amount in dollars
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| tip_amount | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It fails to mention whether the tip replaces or adds to an existing tip, any constraints (e.g., positive values), or side effects. This is insufficient for a mutation 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 very concise, with a clear structure including an Args list. While minimal, it is efficient and front-loaded. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params, no annotations), the description still lacks essential context such as effect on existing tips, idempotency, or integration with other cart operations. The output schema exists but is not referenced.
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 description adds minimal semantic value beyond the input schema: it specifies that 'tip_amount' is in dollars, but does not explain format, range, or allowed values. For 'cart_id', it merely repeats the name. With 0% schema coverage, more detail would be beneficial, but the unit clarification earns a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('set') and resource ('tip amount on the cart'). It is straightforward but does not differentiate from the sibling 'post_delivery_tip', which may cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'post_delivery_tip'. The description does not mention prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get real-time tracking info for an active order.
Args: order_id: The order ID to track
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description partially discloses behavior by noting it works for 'active orders', but lacks details on read-only nature, authentication needs, rate limits, or what happens for inactive orders.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and a clear args list. It is front-loaded with purpose, though the args could be better integrated.
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 an output schema, the description need not explain return values, but it does not mention any prerequisites, response format, or error conditions, which are relevant for a tracking tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description's args section adds 'to track' context to the order_id parameter. However, it remains minimal and does not fully compensate for the lack of schema 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 clearly states the tool retrieves real-time tracking info for an active order with a specific verb ('get') and resource ('tracking info'). It distinguishes from sibling tools like get_order and get_order_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_order or reorder. The description does not provide context for when tracking info is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update the quantity of an item in the cart.
Args: cart_id: The cart ID line_item_id: The line item ID to update quantity: New quantity (0 to remove)
| Name | Required | Description | Default |
|---|---|---|---|
| cart_id | Yes | ||
| line_item_id | Yes | ||
| quantity | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes that setting quantity to 0 removes the item, which is a behavioral trait. However, it does not disclose other behaviors like side effects, permissions, or validation rules. No annotations are present to compensate.
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 extremely concise, with the purpose front-loaded and the Args section efficiently listing parameters. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema (not shown), so return values are covered. However, it lacks context on error handling, prerequisites (e.g., cart must exist), and the effect of updating non-existent items.
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 Args section adds meaning to the parameters (e.g., 'quantity: New quantity (0 to remove)'), but the schema coverage is 0%, and the description does not elaborate beyond the obvious purpose of each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('update the quantity of an item in the cart') and the specific resource (cart item quantity). It distinguishes itself from siblings like add_to_cart (adds new item) and remove_from_cart (removes entire item).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description does not mention when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update user profile information. (AUTH'D)
Args: first_name: New first name last_name: New last name phone: New phone number
| Name | Required | Description | Default |
|---|---|---|---|
| first_name | No | ||
| last_name | No | ||
| phone | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It mentions '(AUTH'D)' indicating authentication, but does not state whether the update is partial (only provided fields) or full replacement, what validation occurs, or what the response contains. The output schema exists but is not referenced.
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 extremely concise: one sentence plus a list of parameters with short explanations. It is front-loaded with the action and list structure. Every sentence is necessary and no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 optional parameters, no annotations, and an output schema, the description is incomplete. It does not explain that all fields are optional and updates are partial, nor does it refer to the output schema for return value details. More context on usage semantics 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 coverage is 0%, so the description must add meaning. It provides brief definitions ('New first name' etc.) which clarify each parameter's purpose beyond the schema's type/null info. However, it lacks constraints like formatting, length, or allowed values, leaving gaps.
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 'update user profile information' and lists specific fields (first_name, last_name, phone). No sibling tool offers the same functionality (e.g., get_profile is read-only, change_password is for password). The verb and resource are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not clarify that password changes should use 'change_password' or that address updates require 'add_address'. The description lacks any when-not-to-use or context-based recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a one-time passcode and complete login.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| code | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions 'complete login' but does not specify side effects (e.g., session creation), error conditions, or security implications. This is insufficient for a login action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, front-loaded with the key action. Every word is meaningful, with no redundancy or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature (2 required params, output schema exists), the description is minimally adequate but lacks crucial details about return values, error handling, and post-login state. It covers the basic purpose but not enough for a secure authentication step.
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 adds no details about the parameters beyond their names. While 'email' and 'code' are intuitive, the description should elaborate on format, length, or constraints to compensate for the missing schema 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 clearly states the tool's purpose: verify an OTP and complete login. It distinguishes from sibling tools like send_login_otp (which sends the code) and login (which may use password), making the specific action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool should be used after receiving an OTP, likely from send_login_otp. However, it does not explicitly mention when not to use it or provide alternatives, though the flow is implied by sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0add_addressadd_campus_card_paymentadd_favoriteadd_payment_to_cartadd_to_cartapply_gift_cardapply_promo_codeautocomplete_searchchange_passwordcreate_accountcreate_cartestimate_usc_retail_swipe_valueget_addressesget_campus_card_balancesget_cartget_cart_billget_cart_payment_optionsget_favoritesget_gift_card_balanceget_menuget_menu_itemget_orderget_order_historyget_ordering_guideget_payment_methodsget_profileget_restaurantget_session_infoget_usc_meal_plan_rulesloginlogoutplace_orderpost_delivery_tipremove_favoriteremove_from_cartreordersearch_campus_restaurantssearch_restaurantssend_login_otpsend_password_resetset_incomplete_delivery_locationset_pickup_infoset_tiptrack_orderupdate_cart_itemupdate_profileverify_login_otpScored across 47 tools
Most tools have clear distinct purposes, but get_menu and get_restaurant are described as identical, and search_campus_restaurants overlaps with search_restaurants using CAMPUS location_mode, causing minor ambiguity.
All tools use a consistent verb_noun pattern (e.g., add_address, create_cart, place_order) with descriptive names, making them predictable and easy to understand.
47 tools is high, bordering on too many for a single server, but the breadth of Grubhub's ordering, account, and campus-card features justifies the count. Still, it feels heavy for an agent to manage.
The tool set covers the full ordering lifecycle from search to payment and tracking, including campus-specific features. Missing only minor items like canceling an order or updating a cart's delivery address.
An MCP server that exposes functionalities to use Zomato's services.
Hosted MCP server to manage a restaurant menu from AI agents - 39 tools over the DuckHub API.
Public MCP server for discovering open jobs. Search, filter, and get application links.
MCP server for US nursing facility search and ownership lookup (NursingHomeDatabase).
