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

Annotations already indicate idempotent, non-destructive, read-write. The description adds meaningful behavior: determinism, seeded Monte Carlo reproducibility, always-named assumptionsSource, and every simplification listed in projection.assumptionsApplied. This goes beyond the annotations and gives the agent expectations about response content and repeatability.

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 description is dense but front-loaded with the core action and outputs, then packs the assumptions modes and response contract into the second sentence. 'show your work' is stylistic but harmless and reinforces the transparency promise. No wasted sentences, though the long dash-heavy structure could be easier to parse.

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-parameter tool with no output schema, the description does substantial work: it lists output categories, names the assumptionsSource and assumptionsApplied response fields, and explains all major invocation modes. It stops short of describing error behavior or return envelope, but an agent can confidently invoke the tool and interpret the result.

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 only 17%, so the description must compensate. It explains the assumptions alternatives (custom, profile, default) and the seeded Monte Carlo concept, and 'stored household' implies the id parameter. However, it does not explain horizon semantics (startYear, years), api_key, or the numeric meaning of fields like annualReturn, inflationRate, or returnVolatility, leaving those to the 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?

The description names a specific verb ('run'), a specific resource ('stored household'), and a concrete deliverable ('multi-year projection') with enumerated output categories (income, RMDs, tax, expenses, cash flow, net worth). This clearly distinguishes the tool from siblings like get_household or run_model even without an explicit sibling comparison.

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 gives clear usage context for choosing assumptions: pass your own, pin a profile by id+version, or omit both for the illustrative default. It also explains when Monte Carlo is relevant (seeded, same seed same result). It does not explicitly state when not to use this vsul alternative tools, but the guidance is clear for the primary decision an agent faces.

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