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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds meaningful context beyond that: credentials will be visible in the AI conversation context (a security caveat the agent needs) and the required auth flow. It does not explain what 'connecting' changes for the domain or reversibility, keeping 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?

Two short, front-loaded blocks: the action sentence with the credential-visibility warning, then the ACCESS note. Nothing is redundant, though the access block is slightly verbose relative to the core action.

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 a 3-param mutation tool with a nested credentials object, no output schema, and destructiveHint, the description covers the essentials an agent needs: what it does, the auth precondition, and the credential-exposure caveat. Only the alternative-tool routing and post-connect effects are missing.

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 id, provider, and credentials are already documented in the schema. The description only adds the phrase 'provider-specific credentials,' which reinforces but does not extend schema meaning. Baseline 3 applies when the schema carries the parameter detail.

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 and resource ('connect a generic DNS provider to a domain'), and the word 'generic' implicitly contrasts with sibling tools connect_cloudflare and connect_godaddy. It is clear what the tool does, though it never names the provider-specific alternatives explicitly.

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?

Provides access prerequisites (needs a Proof account, authenticate via /mcp or start_login before calling again), which is useful operational guidance. However, it does not say when to use this generic connector versus connect_cloudflare/connect_godaddy or create_dns_credential, so the key selection decision is left to inference.

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