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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explicitly states the tool returns cached metadata and never observation rows, and it explains the response_format behavior including the fallback strategy. This goes beyond what annotations provide, though it doesn't detail every edge case.

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 core purpose in the first sentence, and the parameter details are organized in a clear Args block. Every sentence earns its place, especially the fallback instruction. It is slightly verbose in the response_format explanation, but the detail is necessary given the 0% schema coverage.

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 tool has an output schema, the description doesn't need to explain return values. It covers the key contextual needs: what the tool returns (cached columns/types and row count), what it never returns (observation rows), and how to handle the response_format edge case. The only minor gap is that it doesn't explicitly state when to use 'structured' or 'both' beyond their definitions, but the fallback instruction covers the most common scenario.

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 description must compensate. It explains dataset_id as 'Id returned by stage_url', which is critical provenance information not in the schema. It also explains response_format's enum values in detail ('auto' means no preference, 'text' sends CSV in text channel, 'structured' as typed fields, 'both' in both) and gives a practical use case. This is strong compensation for the lack of schema descriptions, though it could have been slightly more concise.

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 ('Return cached columns/types and row count') and resource ('staged statistical dataset'), and explicitly distinguishes itself from observation-row retrieval ('never observation rows'). It clearly differentiates from siblings like query_dataset and inspect by focusing on cached metadata of a staged dataset.

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 provides explicit when-to-use guidance: it is for inspecting a staged dataset's cached columns/types and row count, and it explicitly says 'never observation rows', which tells the agent not to use it for row-level data. It also gives a concrete conditional instruction: if a summary was received but no column table, call again with response_format='text'. This is actionable and clear.

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