cap_table_update_cap_table_stakeholderEdits an EXISTING stakeholder's identity (name, type, email, metadata) by id. FULL REPLACE; type is effectively immutable. To ADD a new stakeholder use CreateCapTableStakeholder; for an investor contributing capital use RecordCapTableInvestment.
| Name | Required | Description | Default |
|---|---|---|---|
| stakeholder | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations, notably 'FULL REPLACE' and 'type is effectively immutable.' These are important because they warn the agent about replacement semantics and a field that should not be changed. However, it doesn't fully explain what happens to omitted fields (e.g., cleared vs retained), but the annotations already cover the tool's safety profile, so the extra disclosure is helpful.
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 sentences, front-loaded with the primary action, then key caveats, then alternatives. Every sentence earns its place. No filler or repetition.
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 complex nested-schema tool, the description covers the essential behavioral points: what it edits, full replace semantics, type immutability, and alternatives. It doesn't explain return values, but an output schema exists. The main gaps are the id requirement ambiguity and not explicitly stating how missing fields are treated, but overall it is reasonably complete.
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?
The description adds meaning beyond the raw schema by naming editable fields and warning that type is immutable. However, there is a crucial ambiguity: the schema only requires 'name' inside the stakeholder object, but the description says updates happen 'by id.' This could mislead an agent into omitting the id. The 'FULL REPLACE' semantics are stated but not elaborated, leaving uncertainty about omitted fields. Schema description coverage is low, so the description needed to carry more weight.
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 'Edits an EXISTING stakeholder's identity (name, type, email, metadata) by id.' It uses a specific verb ('Edits') and resource ('stakeholder'), and the phrase 'EXISTING' distinguishes it from create operations. Sibling differentiation is explicit via references to CreateCapTableStakeholder and RecordCapTableInvestment.
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 explicitly says when to use this tool vs alternatives: 'To ADD a new stakeholder use CreateCapTableStakeholder; for an investor contributing capital use RecordCapTableInvestment.' This provides clear when-to-use and when-not-to-use guidance, which is rare and highly useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Multiple tool pairs are nearly identical (formation_extract_cap_table / formation_extract_cap_table_ocr; formation_start_formation / formation_create_formation), and several tools lack descriptions, making selection ambiguous. The scale of 202 tools with overlapping summaries (e.g., multiple cap-table summary tools) compounds the confusion.
Dominant snake_case `module_verb_noun` pattern, but with notable deviations: `captable_send_safe_for_signature` uses an inconsistent abbreviation, `check_company_name_availability` lacks a module prefix, and `get_list_` vs `list_` prefixes are mixed. Readable but not fully consistent.
202 tools is far beyond any reasonable surface for a single server, even a broad platform. The sheer number overwhelms and makes tool discovery impractical; many tools are peripheral (ads metrics) to the core formation purpose.
The domain appears well covered: formation flows, cap-table lifecycle (import, close, simulate), accounting (journal entries, periods, schedules), cards, documents, and transactions all have CRUD or lifecycle operations. Minor gaps exist (e.g., no card deletion, no counterparty creation), but they are unlikely to cause dead ends.