csv_to_bundle

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

With no annotations present, the description carries the full burden and does so: it discloses that only header-to-field mapping occurs, no model is involved, nothing is retained, the call is never counted/free, and the size limit is ~1 MB. It also warns about the failure mode (silently missed timestamp/count columns) and lists the returned diagnostic fields.

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?

Front-loaded with the purpose, then parameter mechanics, then a compact WHEN/WHEN NOT block. Three tight paragraphs and no filler; the caution about unmapped columns earns its space by preventing a silent failure.

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?

No output schema exists, and the description compensates by naming the return payload (bundle, mapped_columns, unmapped_columns, warnings) and how to act on it. It also covers cost/retention behavior that no annotation supplies. Only the unexplained nested site_profile parameter keeps it short of complete.

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%, so the description must compensate, and it does for two of three parameters: csv_text is clarified as inline text rather than a path with a rough size cap, and kind is given its two valid values ('shift-report' or 'oee'). The nested site_profile parameter is never mentioned, which is the remaining gap.

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 concrete transformation ('turn a raw CSV export ... into the bundle shape run_agent expects') and names the exact backing endpoint, so the agent knows the verb, the input resource, and the output shape. It is clearly distinguishable from siblings like run_agent, which consumes the bundle this tool produces.

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?

Contains explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, naming the two alternatives (data already arriving as structured UNS events, or assembling the bundle directly from a readable source). This is the clearest possible routing guidance.

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