add_rows

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

With no annotations provided, the description carries the full disclosure burden. It does this well by explaining that invalid rows are rejected while valid rows are saved, that the call is limited to 100 rows, and that rejected rows are reported with plain-language reasons. It also provides the complete return shape, making side effects and failure behavior transparent.

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 organized into a clear summary, usage note, Args, Returns, and Example. Every section adds necessary information: the prerequisite check, the limit, the return contract, and a concrete example. There is no filler or redundancy that dilutes the guidance.

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 two-parameter tool with no annotations, the description is complete: it explains when to use it, how to prepare, what the inputs mean, what outputs look like, and how to handle rejected rows. The example further anchors the expected call shape. No critical operational detail 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 description coverage is 0%, so the description must fully compensate. It clearly explains that dataset is the exact dataset name with an example, and that rows is a list of row objects mapping column names to values with an inline example. It also adds the 100-row limit and validation behavior that the schema does not convey.

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 opens with a specific verb and resource: 'Add one or more rows to a dataset with per-row validation.' It clearly identifies the operation as adding rows and even differentiates its behavior from related tools by emphasizing validation and partial saves.

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?

It gives clear usage context: use this to capture records the user dictates in conversation, check describe_dataset first to ensure columns and constraints match, and relay rejected rows. It does not explicitly enumerate when not to use it versus alternatives like import_rows or update_rows, so it misses the full explicit when-not guidance.

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