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

Annotations already declare readOnly/non-destructive, but the description adds substantial behavioral context beyond them: connected endpoints are searchable and unconnected ones are not 'by design', the copy-it-yourself vs hand-over-link decision depends on cross_workspace_access state, and the hard constraint that the agent cannot connect anything and must never ask a human to paste credentials.

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-loads the purpose, then the search behavior, then the routing rules. It is long and dense but nearly every sentence carries distinct routing or safety value. Slightly heavy for a summary line, but no clearly wasted content.

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 fills the gap by describing the return payload: lanes (oauth/key/provision/broker), connected flag, public page, connect_url, and copyable_from with copy_url. Combined with full parameter coverage and annotation safety hints, an agent has everything needed to call and act on results.

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 all three parameters (limit, query, connected) are already documented in the schema. The description adds only marginal framing ('narrow by name or purpose', 'leave it blank to list everything'), which largely restates the query parameter's own schema text. Baseline 3 applies.

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 ('see what services Connections can connect - the whole connector registry') with concrete examples, and explicitly contrasts with the sibling connections_search_catalog by noting that only connected connectors' endpoints are searchable there. An agent can distinguish this registry-listing tool from the catalog search without opening either 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: pass a query to narrow vs blank to list all, use connections_search_catalog for a connected connector's endpoints, hand over connect_url when a needed service is missing, copyable_from/copy_url for other workspaces, and connections_copy_connection when cross_workspace_access is ON. It even states the boundary condition 'both workspaces are solely the member's'.

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