get_connection

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

Without annotations, the description carries the full burden. It reveals that the tool is a read operation ('gets'), clarifies that connections are non-destructive, and explains the effect of the 'with_secret' parameter on the return value. However, it does not explicitly state permissions needed or any other behavioral nuances like rate limits, but the detail is adequate for a simple read tool.

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?

The description is well-structured: one-line summary, explanatory paragraph, related tools, parameter details, return details, and an example. It is front-loaded with the core purpose and uses minimal but necessary text. No redundant sentences.

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?

The description covers all major aspects: purpose, usage comparison, parameter semantics, return structure, and an example. It lacks only minor details like prerequisites or explicit read-only indication, but for a 3-parameter read tool with no output schema, it is nearly complete.

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?

Input schema has 0% description coverage, so the description must compensate. It does so thoroughly with an 'Args' section defining each parameter: 'domain_identifier' (pattern), 'identifier' (length constraints), and 'with_secret' (default, purpose). This adds significant meaning beyond the bare schema.

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 clearly states 'Gets a connection in Amazon DataZone', specifying the verb and resource. It also distinguishes 'connection' from 'data source' by explaining that connections are credentials+config while data sources are specific locations, differentiating it from the sibling tool 'get_data_source'.

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?

The description includes a 'related tools' section explicitly contrasting with 'get_data_source', telling when to use each: 'get_connection' for metadata and config, while 'get_data_source' for detailed information about a specific data location. This provides clear when-to-use and when-not-to-use guidance.

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