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

Annotations already cover readOnly/destructive/closed-world, but the description adds real behavioral context: the auth prerequisite ('authenticated active company access'), idempotency ('safe to repeat'), canonicality ('reads current server state and does not manufacture company facts'), and the important clarification that rendering is not consent or issuance. The 'Confirmation boundary' sentence is largely boilerplate covering unrelated action types, which dilutes rather than contradicts the value.

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 purpose is front-loaded and the labeled sections (Prerequisite, Canonicality, Idempotency, Confirmation boundary) aid scanning. However, the confirmation-boundary sentence enumerates unrelated operations ('reversible save, explicit fact/evidence record, link preparation, plan refresh') that are irrelevant to a read tool, adding length without value.

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?

With no output schema, the description carries the return-value burden and does so: issued shares, ownership percentages, projected status, authorized and unissued shares, plus rendered UI elements. Prerequisites and the pre/post-incorporation distinction are covered. The remaining gap is parameter-level detail, which is left entirely to the undocumented schema.

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%, and the description says nothing about companyId or the nested _corply_context object (with its minLength constraints and dependentRequired receipt/id rule). With zero schema coverage the description is expected to compensate, and it does not — an agent gets no help on what either parameter means or when the context object is needed.

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 states a specific verb and resource ('Return the company's ownership ledger') and disambiguates two operational states: incorporated companies get issued shares and ownership percentages, pre-incorporation gets a projected cap table with authorized/unissued shares. It is clear enough to distinguish from generic reads, but it never names the close sibling get_company_stock_ledger or import_cap_table, so an agent must still infer the boundary.

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 concrete when-to-use guidance: call proactively in Codex with MCP Apps while reviewing saved founder equity or the final application, without waiting for the founder. That is a clear trigger condition. It stops short of naming alternatives or when-not-to-use cases (e.g., versus the stock ledger tool), so it is not a 5.

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