connect

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

Annotations only say readOnlyHint=false and openWorldHint=false; the description adds the important behavior: for key-based apps it surfaces where to obtain the key plus the terminal command to store it, and for Google it kicks off browser sign-in and returns immediately (user approves out-of-band, next call works). This is exactly the async/side-effect context the annotations cannot convey.

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 compact sentences, front-loaded with the core action, then mode-specific behavior, then the sibling pointer and the safety rule. Every sentence carries distinct information; nothing is redundant.

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 no output schema, the description carries the burden of return expectations and does so for the Google path ('returns at once... the next call works'), though what connect returns for key-issuing apps is only implied. Failure modes (invalid app, already-connected app) and the OAuth-client prerequisite for Google are mentioned but not fully specified.

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% and the enum already lists the eight apps, so the baseline would be 3. The description adds value beyond the schema by tying semantics to specific enum values: key-issuing apps produce key instructions, and Google requires the user's own OAuth client to be set before the browser flow. It does not elaborate on the remaining enum members.

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 and resource ('Connect one app this server uses'), names the sibling to use for the read-only counterpart, and differentiates the two behavioral modes (key-issuing apps vs. Google OAuth). An agent can identify this tool's job without opening the schema.

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?

Explicit when-to-use routing is given: call `connection_status` to see which apps are connected, and a hard negative rule ('Never ask the user for a key in the chat'). The Google flow's async condition is also stated so the agent knows a follow-up call is expected rather than an immediate result.

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