mcp-coda

Overview Schema Source Related Servers Discussions Admin

Coda Insert Rows

coda_insert_rows

Insert or upsert up to 500 rows into a Coda table using column names. Use key_columns to update matching rows in bulk and track async operations via requestId.

Instructions

Insert one or more rows into a Coda table, with optional upsert.

Inserts up to 500 rows per call. Use column names (not IDs) in the cells. With key_columns, matching rows are updated (upsert) instead of inserted — this is the only way to bulk-update rows. Returns a requestId for async mutation tracking via coda_get_mutation_status. The operation is async (202).

Input Schema

TableJSON Schema

Name	Required	Description
`rows`	Yes	List of rows to insert. Each row is a dict with 'cells' key containing a list of {column: name, value: val} objects. Example: [{'cells': [{'column': 'Name', 'value': 'Alice'}]}]
`doc_id`	Yes	The doc ID containing the table
`key_columns`	No	Column names to use as upsert keys. If a row matches on these columns, it is updated instead of inserted. Omit for pure insert.
`table_id_or_name`	Yes	Table ID or name to insert rows into

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.14Jun 10, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations declare only readOnlyHint=false and openWorldHint=true, so the description carries real weight: it discloses the 500-row-per-call cap, the async 202 behavior, the requestId return, the tracking tool, and the upsert semantics. These are concrete operational traits an agent cannot get from the annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action is front-loaded in the first sentence, and every following sentence adds a distinct constraint (limit, column naming, upsert behavior, async return). No filler or redundant restatement of the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter write tool with an output schema present, the description covers the mutation safety profile, the bulk limit, async behavior, upsert path, and the tracking follow-up. Nothing essential to invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics by requiring column names rather than IDs inside cells and clarifying that key_columns is 'the only way to bulk-update rows.' That extra guidance exceeds what the schema alone conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (insert rows into a Coda table) with the added scope of optional upsert. It distinguishes itself from siblings by noting it is the only way to bulk-update rows and by naming coda_get_mutation_status as the tracking companion. An agent can tell it apart from coda_update_row and coda_list_rows without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains when key_columns triggers upsert versus pure insert, and points to coda_get_mutation_status for async tracking. It does not name coda_update_row as the alternative for single-row edits, leaving that inference to the agent. Clear context overall but no explicit when-not-to-use statement.

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

Deploy Server