Update a Grubhub user's profile by changing first name, last name, or phone number; authentication required.
Update user profile information. Requires authentication.
Args: first_name: New first name last_name: New last name phone: New phone number
| Name | Required | Description | Default |
|---|---|---|---|
| phone | No | ||
| last_name | No | ||
| first_name | No |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Changes observed during successful MCP inspections.
v1.1.7Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the authentication requirement, which is useful, but says nothing about the critical ambiguity that all three parameters default to null — whether null means 'leave unchanged' or 'clear the field', nor whether the update is partial or full. That gap matters 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 opening sentence is front-loaded and the description is short. However, the three-line Args block is pure repetition of the input schema and consumes space without adding information, weakening the structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be described. But for a three-parameter mutation with no annotations, the description omits partial-update behavior, null-field semantics, permission scope beyond 'authentication', and effects on unmentioned fields — too much is left unspecified.
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 all three parameters are nullable with null defaults. The Args block merely restates each parameter name as 'New <field>', adding no meaning beyond the schema titles, and fails to resolve the null semantics that the schema leaves ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Update user profile information'), which is clear on its own. However, it does not distinguish itself from the sibling get_profile or explain how it relates to read vs write profile operations, so an agent must infer the split.
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 only usage signal is 'Requires authentication,' which is a prerequisite rather than guidance. There is no statement of when to call this instead of get_profile, whether partial updates are allowed, or what triggers the need to change profile fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.