stack_datasets

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

With no annotations, the description carries the full behavioral burden: it discloses that a new leading dimension is created and that inputs must be exactly shape- and column-compatible, which is meaningful. It omits whether the source datasets are consumed or left intact, whether mismatch raises an error, and how labels/axis naming affect ordering — gaps for a mutation-shaped operation.

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?

Two sentences, front-loaded with the operation and immediately backed by a concrete shape example, with the compatibility constraint following. No redundant restatement of the tool name and nothing that could be trimmed without losing information.

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?

Because an output schema exists, the description need not explain return values, and it does explain the resulting dimensionality plus the input compatibility contract. The unresolved gap is parameter-level meaning and failure behavior, which keeps it from being fully complete for a four-parameter tool.

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 0% across four parameters and the description never names or explains names, labels, new_name, or axis_name. Only the leading-dimension concept and the ticker example indirectly hint at what labels/axis_name control; an agent must guess at new_name and label ordering from the schema titles alone.

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?

States a specific verb and resource ('stack ... tables ... or tensors along a new leading dimension') and makes the shape of the result concrete with 'one CSV per ticker -> ticker x row x column'. It also distinguishes itself from the alignment siblings by naming subset/tensorize as preparatory steps, though the boundary with tensorize itself could be sharper.

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?

Gives a clear precondition for use ('shapes and column sets must match exactly') and routes the agent to subset/tensorize to satisfy it, which is actionable guidance. It does not state when to avoid stacking or what happens when the precondition fails, so it stops short of full when/when-not coverage.

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