upsert_mcp_server

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently states three key behaviors: the entry is replaced wholesale (not merged), the rest of the file is untouched, and the previous file is backed up. These are critical side-effect and safety details that go beyond a simple 'add or replace' statement. No annotation contradiction 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 structured effectively: a clear action sentence, followed by critical behavioral notes, a usage workflow, and an example block. All content is relevant and purposeful. While it is slightly longer than average, the example is justified because it illustrates the non-obvious structure for a stdio entry. No fluff or redundancy is present.

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

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

Given that an output schema exists (context signal indicates has output schema true), the description does not need to explain return values. Combined with clear parameter descriptions and an example, the description provides everything an agent needs to call the tool correctly: what it does, how to read first, what the entry structure looks like, and the side effects. The workflow is fully specified, making this highly complete for the tool's complexity.

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

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

Schema coverage is 100%, so both parameters have descriptions in the schema (name as a key string, config as a full entry object). The description adds meaningful value beyond the schema: it provides a concrete stdio entry example with structure, and explains that the entry is replaced wholesale, which clarifies what the `config` object is expected to contain and how it is handled. This extra context earns a score above the baseline of 3.

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

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

The description clearly states the exact action: "Add or replace one server entry in config/mcp.json." It specifies the target file and the scope (one entry), distinguishing it from sibling tools like `get_mcp_config` (read), `delete_mcp_server` (remove), and `replace_mcp_config` (likely whole-file replacement). The verb is specific and the resource is 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 gives explicit workflow guidance: "read the current entry with `get_mcp_config` first and send it back with your change applied." This tells the agent how to use the tool correctly. It also implies the alternative (read before write) and clearly states that the entry is replaced wholesale, not merged. However, it does not explicitly name sibling tools like `replace_mcp_config` for whole-file replacement, though the distinction is implied by "one server entry."

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