upsert_menuCreates or edits a press-1 menu. The account owner needs Business. A key can ring a person, ring a queue, or send the caller to an AI receptionist. A direct person target and every queue agent also need Business.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| keys | No | Press-1 choices. Sending keys replaces the menu's choices. | |
| name | No | ||
| enabled | No | ||
| greeting | No |
Changes observed during successful MCP inspections.
Input schema / properties / keys / descriptionAdded value: +"Press-1 choices. Sending keys replaces the menu's choices."Input schema / properties / keys / items / additionalPropertiesAdded value: +falseInput schema / properties / keys / items / propertiesAdded value: +{
+ "consumer_user_id": {
+ "description": "Person on this account when target is user.",
+ "type": "string"
+ },
+ "digit": {
+ "description": "Key the caller presses, such as 1.",
+ "type": "string"
+ },
+ "queue_id": {
+ "description": "Queue on this account when target is queue.",
+ "type": "string"
+ },
+ "receptionist_id": {
+ "description": "AI receptionist on this account when target is ai_receptionist.",
+ "type": "string"
+ },
+ "target": {
+ "description": "user rings a person. queue rings a queue. ai_receptionist sends the caller to an AI receptionist.",
+ "enum": [
+ "user",
+ "queue",
+ "ai_receptionist"
+ ],
+ "type": "string"
+ }
+}Input schema / properties / keys / items / requiredAdded value: +[
+ "digit",
+ "target"
+]Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is known without the description. The description usefully adds plan/permission requirements (owner needs Business; person targets and queue agents need Business), which is real operational context. It does not, however, restate the destructive replace semantics of keys—that lives only in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the purpose and with no filler. Each sentence carries either the operation, an eligibility rule, or target semantics, so nearly every line earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with annotations but no output schema, the description covers purpose, plan requirements, and target types. It omits how id toggles create vs edit, what happens when keys are absent, and the replace behavior of keys, leaving an agent to infer the upsert semantics from the name alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, so the description must carry more of the load. It explains the target types (person, queue, AI receptionist), but that largely duplicates the enum descriptions already in the schema, and the top-level parameters id, name, enabled, and greeting get no explanation anywhere. It does not compensate for the coverage 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?
The description opens with a specific verb+resource: 'Creates or edits a press-1 menu,' which plainly conveys the upsert nature of the tool and distinguishes it from configuration siblings like upsert_queue or upsert_receptionist. It stops short of explicitly naming that sibling boundary, so it is clear but not maximally differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states prerequisites ('The account owner needs Business') but never says when to reach for this tool versus alternatives such as upsert_queue or set_number_routing, nor when to avoid it. The caller gets eligibility rules but no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.