Create/update register entries (import a reference table)

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

With no annotations provided, the description fully discloses critical behavioral traits. It details that PUT replaces the entire set and marks missing entries as invalid, which reveals destructive behavior. It also clarifies matching logic (by externalId or code) and the PATCH behavior of leaving other entries untouched. This is transparent and goes beyond a simple 'write' statement.

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 concise and well-structured, using bullet points to present the two modes clearly. The opening sentence establishes the core action, and each detail (match key, invalid marking, entry fields) earns its place without redundancy. It is front-loaded and easy to scan.

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 covers the essential behavior for a complex tool with two modes and no output schema. It explains the mode differences, match key, and entry format. However, it does not clarify the meaning or required format of the 'organization' parameter, nor does it describe the response format or success indicators. These gaps slightly reduce completeness, but the core usage is well-covered.

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 75%, with 'method' and 'entries' having descriptions. The tool description adds significant value by elaborating on the method parameter (explaining PUT vs PATCH semantics) and by specifying the expected entry structure {externalId?, code, description?, isValid?}, which the schema leaves open (additionalProperties). This enhances understanding beyond the schema, though the 'organization' parameter remains unexplored.

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 clearly states the tool's purpose: 'Write entries to a register.' It distinguishes between two modes (PUT and PATCH) and provides the title 'Create/update register entries (import a reference table),' which reinforces the resource and action. This makes it distinct from sibling tools like wflow_get_register and other wflow_upsert_* tools targeting different entities.

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 provides clear guidance on when to use each mode: PUT for full replacement (with ERP reference-table import context) and PATCH for partial updates. It explains the behavioral difference between the two, offering context without explicitly naming alternative tools, but the guidance is sufficient for selecting the appropriate mode.

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