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

Goes well past the annotations: discloses atomicity ('every row lands or none does'), reuse/matching of existing holders, that rounds are recorded as closed history, and server-side rule and total-mismatch refusal. The one gap is `replace`, which can overwrite existing cap table data and is never mentioned, which is notable given destructiveHint=false.

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?

Front-loads the verb and the all-or-nothing guarantee, and every clause (atomicity, reuse, round history, validation refusal) carries distinct information. The lead sentence is long and clause-dense, but for a call with nested 40-field rows it is not wasteful.

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?

An output schema exists, so return-value detail is correctly omitted, and the description covers the failure modes an agent most needs to know (rule violations, total mismatch, partial-write risk). Missing is the overwrite semantics of `replace` and any note on size limits or required permissions, which matter for a whole-cap-table write.

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 17%, but the description compensates for most of it: rows are described as holdings whose named existing holders get matched and reused, round names are tied to closed-round history, and 'the totals the founder confirmed' explains expectedTotalShares/expectedTotalCapital. `replace` and roundTerms pricing fields remain unexplained, leaving a genuine hole in a 6-param schema.

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?

States a specific verb+resource (writes a whole cap table in one call/transaction) and immediately distinguishes itself from the sibling create_cap_table_stakeholder pattern by naming 'a sequence of single writes' as the thing it replaces. An agent can tell it is a bulk-write tool without opening the schema.

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?

Explicit selection rule: 'Use this for any import of more than one holding instead of a sequence of single writes' — a clear threshold plus the alternative class. It does not address adjacent one-off import tools (cap_table_import_safe, cap_table_import_rsa) or when preview/validation-only flows should be preferred, so it stops just short of full routing.

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