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

Annotations declare readOnlyHint=true and idempotentHint=true, so the description need not restate non-mutating behavior. The description goes beyond annotations by clarifying that this is an inspection step in a multi-step workflow, that it produces the table name needed by a sibling tool, and that it errors if DataCanvas is disabled. No contradiction. A small point: it could mention that it returns table names and column types (implied) but still solid given annotations.

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?

Four sentences, each building on the previous: what it lists, when to call, what to do next, and failure mode. Front-loaded with the action and resource. No wasted words.

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?

Given the single, required, well-explained parameter, a complete output schema, and annotations covering safety, the description covers the workflow placement (after fetch, before query), the error condition, and the next step. Nothing needed to call it correctly 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 coverage is 100%, so the schema already describes canvas_id. The description adds context that canvas_id comes from water_get_series or water_find_sites, which is helpful, but does not add a lot beyond that. Since coverage is complete, baseline is 3, and the description earns a 4 by tying the parameter to the exact provenance.

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 ('List'), a clear resource ('tables and columns staged on a DataCanvas'), and the two functions that produce the canvas. This distinguishes it from siblings like water_dataframe_query, which runs queries, and from the data retrieval functions, by tying it to the DataCanvas staging workflow.

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?

Explicitly says to call this after water_get_series or water_find_sites returns a canvas_id, before writing a query, and to then pass the table name to water_dataframe_query. It also names the exact prerequisite sequence and the error condition when DataCanvas is not enabled. This is clear when-to-use and sequential guidance.

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