Aws Query

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

With no annotations, the description carries the full burden of behavioral disclosure. It conveys that operations are read-only, which is a useful safety signal, but it does not mention authentication or profile dependencies, response handling, or any limitations. The description is far from a full picture.

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 a single, clear sentence with no filler. It is front-loaded with the action and the key safety qualifier. While more information would be helpful, the structure is appropriately concise, though the conciseness does border on under-specification.

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 no annotations, zero schema parameter coverage, and a relatively broad sibling set, the description is too thin. The output schema handles return values, but the description fails to mention what makes the tool suitable for its purpose, how to structure the query, that region/service are optional filters, or any prerequisites. This leaves an agent under-informed for invoking it correctly.

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?

The schema contains 0% description coverage, so the description must compensate. It indicates that the query parameter supports natural language, but it does not explain the purpose of the optional region and service parameters, nor does it mention they are optional filters. The names are self-explanatory, but the description adds minimal semantic value beyond them.

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 states a specific action ('Execute read-only AWS queries') and includes a key modifier ('read-only') that distinguishes it from a likely sibling (aws_execute). The resource is somewhat generic ('queries') but the read-only qualifier and the supported natural language make the tool's purpose clear.

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?

No guidance is provided about when to use this tool versus alternatives like aws_execute. The read-only label implies read-oriented use cases, but there is no explicit statement about conditions, prerequisites, or excluded scenarios.

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