run_explore_query

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

With zero annotations, the description carries the full burden of behavioral disclosure, and it delivers richly: it states the operation is a non-persistent preview ('never persisted'), discloses the server-side truncation cap ('capped at 500 rows'), and enumerates the return shape (rows, row_count, truncation flag, ranked chart recommendations). This is precisely the behavioral context an agent needs that annotations would otherwise provide.

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?

A single dense paragraph, front-loaded with the core purpose before moving to sourcing, returns, and downstream usage. Every clause earns its place — the truncation cap, the chart-type list, and the cross-reference to report tools are all load-bearing. It is slightly long in one block and could benefit from clearer segmentation, but there is no waste.

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 moderately complex aggregate-query tool with no output schema and no annotations, the description is notably complete: it covers purpose, input sourcing, return values, truncation behavior, and the downstream report-building flow. The principal gap is the unstated query-assembly semantics for measures/dimensions/filters, though the schema's $defs structure partially mitigates that. An agent can call this tool correctly for a basic query and understands the result shape.

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 0%, so the narrative description must compensate for parameter meaning. It explains dataset_key sourcing ('every column value from list_datasets's output'), but it does not explain the aggregate-query construction semantics — how measures, dimensions, filters, bucket, and limit combine to shape the query. The $defs enums (operators, aggs, buckets) are self-explanatory at a structural level, but the description never tells the agent how to assemble a valid aggregate query, which is the core knowledge for this tool.

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 opens with a specific verb+resource: 'Run a live, ad-hoc aggregate query against a whitelisted dataset — a preview, never persisted.' This clearly distinguishes the tool from its siblings — list_datasets (enumeration), the report tools (persistence/build), and the view dashboards (UI surfaces). An agent can tell exactly what this does without opening the schema.

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 tells the agent where to source inputs: 'Pick dataset_key and every column value from list_datasets's output.' It also connects downstream usage — 'use the first recommendation as the visualization.type when building a report section with create_draft_report/update_draft_report.' This orients the agent within the tool workflow. It lacks explicit exclusions ('don't use this for X'), but the preview-vs-persist contrast with report tools implicitly signals when not to use it.

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