connect

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries most of the burden and delivers real behavior: Google starts a browser sign-in and "returns at once," meaning the call is async and the approval happens out-of-band before the next call works. That async/side-effect detail is genuinely non-obvious. It is slightly unclear whether the "says where to get one and the terminal command" refers to tool output or agent instruction, which keeps it from a 5.

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 action, then branches by app type, then the sibling pointer. Every sentence is doing work, though the Google sentence is dense and the key-issuing sentence is grammatically ambiguous about subject (tool vs. agent).

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 no output schema and full schema coverage, the description covers prerequisites, branching behavior, and post-condition for Google. What is missing is a clear statement of what a non-Google success returns or how the agent verifies the key was stored, which matters without an output schema.

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% and the single parameter is an enumerated list, so the schema fully documents itself. The description never names or elaborates the `app` argument beyond "one app," adding no semantic value over the schema — the correct 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?

States a specific verb ("Connect") and resource ("one app this server uses"), and it is trivially distinguishable from the dozens of app-specific siblings. The reader knows exactly what state change is being requested.

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?

Names the alternative for the related question ("To see which apps are connected, call `connection_status`") and gives per-app branches: key-issuing apps get a key location plus a storing command, Google takes a different OAuth flow. It even supplies an explicit prohibition ("Never ask the user for a key in the chat"), which is strong routing guidance.

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