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

With no annotations, the description carries the full burden, and it discloses genuinely useful behaviors beyond the schema: platform-default fee auto-fill when platformId is supplied, the side effect of also creating an initial_investment event in the same operation, and the v1 SPV-only limitation. It stops short of covering auth/permission requirements or error/reversibility behavior, so it is strong but not complete.

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-loaded with purpose, then ordered caveats (amount format, fee format, platform defaults, optional event, version limit). Each sentence carries distinct information with no filler.

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 15-parameter creation tool with a nested initialInvestment object and no output schema, the description adequately covers format conventions, defaulting behavior, and the composite side effect. It does not address permissions or failure modes, but the core invocation-critical context is present.

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 100%, so baseline is 3, but the description adds real value: it clarifies that all monetary amounts are decimal strings in the deal currency, that fee percentages are fractions in [0,1] and emphatically NOT 8.5, and that omitted fee fields are auto-filled from platform defaults. This goes beyond what the schema descriptions convey.

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 ("Create a venture deal") and immediately disambiguates with the parenthetical "(private/illiquid investment record)", distinguishing it from create_portfolio and create_investment_transaction. An agent can tell it apart from sibling creation tools 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?

Provides contextual constraints (platformId triggers fee auto-fill; initialInvestment triggers event creation; only SPV is supported in v1) but never states when to choose this over siblings like create_venture_event or create_portfolio. Usage is only implied by the resource scope.

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