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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses permission requirements, that preview is a bounded read-only operation, that save re-executes the preview and only creates a dataset when usable rows exist, and that repeated saves create new datasets rather than updating. These are exactly the mutation semantics an agent needs and are not available from the annotations or schema.

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 front-loaded with the operation triad and prerequisites, and every sentence carries operational information. It is dense and clause-heavy, packing several rules per sentence, which slightly reduces scannability but not content value.

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 9-parameter, nested-object, multi-operation tool with an output schema and annotations, the description covers permissions, per-operation required inputs, save-side effects, alternatives, and the MCP-vs-SQL branch. Nothing essential for a correct invocation is missing.

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%, so the baseline is 3; the description still adds cross-parameter conditional logic the schema cannot express, such as preview requiring connectionId plus query or configuration, and save additionally requiring name and projectId. It does not deepen individual parameter values much beyond what the schema already says, so it stops short of 5.

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 first sentence names the three distinct operations (inspect sources, preview a read-only request, save a new dataset) with specific verbs and resources, and later sentences explicitly distinguish the tool from siblings run_dataset and Chartbrew. An agent can tell what this tool does and what it is not for 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?

It states when each operation applies (inspect without connectionId lists connections, with it lists resources; preview needs connectionId plus SQL or MCP config; save additionally needs name, projectId and datasets:write), plus explicit exclusions: use run_dataset for existing datasets and Chartbrew for unsupported sources. Prerequisites (team-admin, datasets:write) are stated up front.

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