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

With no annotations, the description must carry the behavioral load, and it does disclose real traits: the response shape, that values are raw types (string|number|boolean|null), and that results can be truncated with a maxRows default of 1000. It still omits error behavior on invalid AQL and any permission/authorization context.

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?

Purpose is front-loaded, followed by a compact conceptual model, a single worked example, and a response-shape block — each section earns its place and nothing is padding. The response block usefully substitutes for the absent output schema.

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 nested, 5-parameter tool with no output schema and no annotations, the description covers request semantics, response fields, and pagination, which is a lot. The gaps are the unrelated-to-calling omissions: no guidance on sibling selection and no mention of error or permission behavior.

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 the baseline is 3, but the description goes beyond it by explaining that each inner array is a heading expression equivalent to a cell formula, and by mapping rowHeadings/columnHeadings/context to a worked example. That conceptual framing is not recoverable from the schema alone.

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 verb and resource ('Query an Azquo database using AQL') and defines what AQL actually is, which is far more than a restated name. It implicitly distinguishes itself from the write-side sibling aql_write by framing the operation as a query, but it never names that sibling or any alternative 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?

There is no statement of when to choose query_aql over neighbors like aql_write, get_report_data, describe_query, or import_from_query. The example illustrates how to shape a call, not when a call is warranted, so an agent gets invocation mechanics but no routing guidance.

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