Batch insert or update rows in a JSONL table by primary key, returning inserted, updated, and unchanged counts. Use dry-run to preview changes without writing files.
按指定主键批量新增或更新，走与 HTTP 相同的 Store 并发保护。返回回执：inserted / updated / unchanged 计数与各自的主键值列表。dry_run=true 只算回执不落盘。
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| rows | Yes | ||
| table | Yes | ||
| dry_run | No | 只返回将发生的变更，不写文件 | |
| library | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavior disclosure, and it delivers: it mentions Store concurrency protection, the exact receipt format (inserted/updated/unchanged counts and key lists), and the no-persistence behavior of dry_run=true. It does not cover error or validation behavior, but the most decision-relevant side effects are explicit.
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?
Three compact sentences cover the core operation, concurrency protection, return receipt, and dry-run behavior. The most essential verb and scope are front-loaded with no redundant filler.
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?
The description compensates for the missing output schema by stating the receipt shape, and it covers the operation's key nuances. It lacks row-structure details and failure semantics, which would help for a 5-parameter mutation tool, but it is sufficiently complete for a competent agent to call the tool correctly in the common case.
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 only 20%, with only dry_run documented. The description adds meaning by identifying key as the primary key, rows as the batch payload, and clarifying dry_run semantics. However, it does not explain how rows should encode the key or what values library/table expect, leaving part of parameter construction to inference.
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 (upsert) and a clear resource (rows keyed by primary key). This immediately distinguishes it from the read-only and metadata sibling tools like query and list_tables, so an agent can tell what it does without needing more context.
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 conveys that the tool is for batch insert-or-update operations by primary key and even highlights the dry_run inspection mode. However, it never explicitly contrasts it with alternatives such as query for reads or states when not to use it. The usage context is clear but the tool-selection guidance is only implied, not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.