Attach or update an agent MCP server

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

Goes well beyond the annotations: explains that server_id is validated against the caller's catalog, that identity fields (type, server_id, secret_id, mcp_server_url) cannot be spoofed from the body, that attach can succeed before OAuth completes, and that runs can spend credits. This is exactly the side-effect/permission context the destructive/openWorld annotations cannot express. Note a mild tension: 'upsert' reads as idempotent while idempotentHint=false, but the explicit 'never resubmit unknown outcomes automatically' warning resolves it in favor of the annotation.

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?

Front-loaded with the core verb and upsert semantics, then layered with the spoofing rule, OAuth caveat, and confirmation warning. Every sentence carries information, though the confirmation/credit paragraph could be tightened slightly.

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 destructive, open-world mutation with no output schema, the description covers the identity-validation model, the confirmation requirement, the credit/downstream-action risk, and even mentions auth_status as a return signal. An agent has everything needed to invoke it correctly and safely.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: it scopes server_id to the caller's catalog, explains that the request body carries only free-form connector configuration, and notes that identity keys in the body are ignored. It says little extra about confirm/account beyond what the schema already documents.

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+resource ('Attach an MCP server (connector) to an agent') and immediately clarifies the upsert behavior, which cleanly separates it from the sibling detach_agent_mcp_server and the read-only list_agent_mcp_servers/retrieve_mcp_server tools.

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

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

Clearly conveys when to use it (attach, or update config if already attached) and adds a hard gate: 'Explicit confirmation is required for this exact account operation' plus a warning against automatic resubmission of unknown outcomes. It does not explicitly name detach_agent_mcp_server as the counterpart operation, so routing is implied rather than spelled out.

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