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

Annotations carry the safety profile (destructiveHint=true, readOnlyHint=false, openWorldHint=true) and the description adds substantial non-obvious behavior: agent-added rows are removed on request while other rows require the server's credential-free probe to return a vendor no-such-route answer; unreachable vendors leave rows in place with an explanation; bulk calls judge each row independently and report the justifying probe. No contradiction with annotations.

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?

All six sentences carry distinct functional content and the highest-stakes information (what gets removed and under what conditions) is front-loaded. The middle clause ('the server's own credential-free probe of the vendor gets the vendor's published no-such-route answer') is dense and slightly convoluted, but the length is justified by the tool's conditional behavior.

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 tool with no output schema, the description is remarkably complete: it covers both use cases, all three targeting modes, the conditional removal policy for agent-added vs. all other row origins, failure behavior for unreachable vendors, per-row probe reporting, and the preferred alternative for fixing rows. An agent has everything it needs to decide whether, how, and with what expectation to invoke it.

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%, so parameter meanings are already documented. The description adds genuine value by explaining how to choose among the targeting lanes (endpoint_id/tool_name for single, endpoint_ids for bulk), the 'aws' service default, the max-200 cap, and the independent per-row judging semantics — going beyond the baseline 3 without fully compensating for the absence of output-schema 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+resource ('Remove catalog rows') and immediately distinguishes the two intended use cases: repair of a bad/duplicate agent-added row and cleanup of rows whose vendor deleted the route. The final sentence explicitly contrasts with connections_catalog_add, so an agent can tell these siblings apart 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?

Gives explicit when-to-use guidance for both lanes (repair vs. cleanup), explicit targeting guidance (ONE by endpoint_id/tool_name vs MANY by endpoint_ids), and explicitly names the alternative: 'To FIX a row in place instead of deleting it, just re-run connections_catalog_add.' Nothing 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.