get_distribution

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

The description discloses detailed algorithmic behavior: numeric columns get equal-width bins between min/max, datetime gets time-bucket bins, and categorical/string get top-n + 'other' bucket. This goes far beyond the readOnlyHint annotation, providing actionable insight into how the tool operates without needing to invoke it.

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 two sentences, front-loaded with the core purpose, and every phrase earns its place. The compact type-specific breakdown and the 'token-cheap' usage hint are efficient and memorable.

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 tool with no output schema, the description fully explains the return concept (bin-counts) and the per-type behavior. It is complete enough for an agent to select and invoke the tool confidently, even without edge-case details.

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?

The schema covers all parameters (100% coverage) with descriptions for bins, column, and dataset. The description adds value by explaining how the 'bins' parameter is applied differently per column type (e.g., top-n for categoricals), which is not explicitly stated in the schema. This gives the agent a better mental model of parameter behavior.

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 clearly states the tool's function: 'Unified bin-counts for any column type' with specific behavior for numeric, datetime, and categorical columns. It distinguishes itself from sibling tools like get_correlations and describe_column by focusing on distribution binning and being token-cheap.

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 clear usage context: 'Token-cheap way to ask what does this column look like?' This implies it is for quick exploratory analysis. While it does not explicitly name alternatives or when-not-to-use, the phrasing effectively guides the agent toward this tool for lightweight column profiling.

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