aras_describe_query

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is a read-only inspection operation (describes structure) and implies it returns structural information. However, it doesn't disclose what the output format is, whether it requires any special permissions, or any side effects (though it's clearly non-destructive). The description is adequate but minimal; it doesn't add rich behavioral context beyond the obvious read-only nature.

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, concise sentence that front-loads the core purpose and includes a usage directive. No wasted words. It's appropriately sized for a simple tool with one parameter.

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 simple inspection tool with one parameter and no output schema, the description is fairly complete. It tells the agent what the tool does, what it needs (the query name), and when to use it (before executing). The only gap is that it doesn't describe the return format, but given the tool's simplicity and the lack of an output schema, this is a minor omission. It could also mention that it's a read-only operation, but that's implied.

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%: the parameter 'nome' is described as 'Nome della qry_QueryDefinition' (name of the qry_QueryDefinition). The description adds that the tool describes the query structure, which implies the parameter is the query name, but it doesn't add syntax or format details beyond the schema. Baseline 3 is appropriate since the schema already documents the parameter fully.

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 the tool's purpose: it describes the structure of a saved query, including which ItemType it starts from and which parameters it accepts. This is a specific verb+resource ('describes a saved query structure') and distinguishes it from siblings like aras_run_query (which executes) and aras_list_queries (which lists). However, it doesn't explicitly name those siblings, so it's clear but not fully differentiated.

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 explicitly says 'Da chiamare prima di eseguirla' (to call before executing it), which provides clear usage context: use this before running a query. It doesn't explicitly state when not to use it or name alternatives, but the 'before executing' instruction is a strong usage guideline. It could be improved by mentioning that aras_run_query is the execution counterpart.

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