write_records

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

Annotations already declare destructiveHint=true and non-idempotent, so the mutation risk profile is known. The description earns credit for going beyond that: 'Any write discards the analysis results', the 50-record cap, read-back after applying, and tables that reassign ids ('trust "added", not the ids you sent').

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?

It is front-loaded with the two-sentence summary and the records example arrives before the edge cases. Some sentences are crammed with parenthetical asides ('a load's load case or group, ...', '(midas-nx plan.validate)') that hurt scanability, though each carries real information.

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 destructive, nested-object, five-parameter write tool with no output schema, this covers refusal semantics, id reassignment, size caps, and result invalidation. The notable hole is the preview/apply handshake: the confirm_token is never tied to the stated two-step workflow, so an agent cannot tell how to complete the apply step.

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 carry the load and it only partly does. It explains 'records' well ({id: fields} with a NODE example) and defines the create/update split for 'mode', but 'confirm_token' — clearly the preview/apply token — and the 'product' enum (gen/civil) get no explanation at all.

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?

'Create or update records in one /db or /DESIGN table' gives a specific verb set plus a bounded resource, and it separates the tool from read-only siblings (read_table, describe_table) and from delete_records. The two-step 'preview, then apply' framing further pins down what the tool actually does.

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 operational rules: create refuses existing ids, update refuses missing ids, with the explicit exception of record '1' in DCO/DCTL/LLRF/LMRR/SRDF. It routes the agent to describe_table and read_table for field definitions, but never mentions when to prefer this over the sibling apply_operations, which is the closest alternative.

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