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

Far exceeds what annotations convey: it discloses that without signed_at only a draft is created, that a signed FAST actually writes a stakeholder row and issues an option holding with fixed 24-month/3-month-cliff vesting, and that name mismatches create a duplicate stakeholder row that hides from ownership views but inflates counts. This is exactly the side-effect detail an agent needs for a destructiveHint=true tool.

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?

Dense but front-loaded and almost every sentence adds decision-relevant content; the critical caveat is flagged early and in caps. Slight redundancy between the 'unsigned FAST grants nothing' sentence and the earlier signed_at warning, and the all-caps emphasis is heavy.

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?

Covers the danger zones of a destructive, nested-schema write tool well, and an output schema exists so return values need not be described. Gaps remain: the relationship between granteeName and stakeholderId is never clarified (the text refers to 'PARTY' which is not a schema field), and roundId/sourceS3Uri expectations are unstated.

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?

With only 30% schema description coverage across 10 parameters, the description carries needed weight: it explains the non-obvious semantics of signedAt, prescribes stakeholder_id usage, and pins down fast_terms.equity_percentage format and fast_terms.effective_date format. Several parameters (name, granteeName, roundId, sourceS3Uri, progressTotal, type enum selection) are still unexplained.

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 and resource ('Records a non-SAFE agreement ... against a company') and enumerates the covered types (option, RSU, RSA, FAST, board consent). The 'non-SAFE' framing cleanly separates it from cap_table_import_safe and cap_table_create_cap_table_stakeholder.

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?

Gives concrete when-to-use rules for the riskiest parameter ('Set it ONLY when the person tells you the agreement has been signed, and say what it will do before you do it') and a default behavior ('leaving signed_at empty is always the safe choice'), plus a prerequisite lookup step. It does not name other agreement-creation paths (e.g. import_safe, update_cap_table_agreement) as explicit alternatives.

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