excel_query_dataset

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only "bounded output" as new behavioral context, without explaining what the bounds are (limit default 100 vs maxRows default 10000), what gets truncated, or whether exceeding a bound errors or silently trims.

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?

Two sentences, zero filler, capabilities front-loaded before the usage clause. Nothing redundant with the title or 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 10-parameter analytical tool with no output schema and near-zero schema coverage, the description is too thin. It does not explain the interaction of range/sheet, the two separate row-bound parameters, or the shape of aggregated versus row-level results, all of which an agent needs to call this 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?

Schema description coverage is only 10% (essentially just 'path'), so the description must carry the burden for 10 parameters. It gestures at filters, groupBy, metrics, sort and bounded output, but adds no operator semantics, no distinction between limit and maxRows, and nothing about range, hasHeader, or the metric aliasing field.

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 (query) and resource (Excel dataset) and enumerates the capability set: typed filters, group-by, aggregations, sorting, bounded output. It is clear what the tool does, but it never distinguishes itself from close siblings such as excel_analyze_dataset or excel_read_range, which an agent could easily confuse it with.

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?

"Use for focused analytical questions without changing the workbook" gives implied usage context, but no explicit when-to-use/when-not or named alternatives. With excel_analyze_dataset and excel_read_range in the sibling list, the routing guidance 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.