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

With no annotations provided, the description carries the full behavioral burden and does so: it states the read-only boundary ('Never create transactions or holdings records'), defines the null-and-reason behavior when pre-flow valuations are absent, explains internal-transfer netting for combined TWR and the requirement to confirm both legs, and discloses the 'performance-from-today' fallback when acquisition cost is missing. These are non-obvious edge-case behaviors an agent could not infer from the schema.

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 the purpose and output list, then prerequisites, then edge cases — a sensible ordering. The middle-to-end sentences are dense run-ons stacking several conditional behaviors, which costs some scanability, but almost no content is redundant.

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 multi-sleeve calculation tool, the description covers inputs, prerequisites, and the trickiest modeling decisions, and an output schema exists so return values needn't be spelled out. A minor remaining gap is the absence of any note on failure modes or partial results beyond the TWR-null case.

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 100%, so baseline is 3; the description earns above that by tying FX rates to per-transaction granularity and explaining that TWR requires a valuation immediately before each later external cash flow and at the end date — semantics the 'Value' enum and valuation items alone don't convey. It does not further clarify asOfDate or baseCurrency beyond 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?

States a specific verb and resource ('Analyses an investment portfolio from its transaction history') and then enumerates the exact outputs: net invested capital, current value, absolute return, TWR, CAGR, per-sub-portfolio breakdown and allocation shares. This is clearly distinguishable from siblings like parse_portfolio_csv or compare_investment_vehicles, which parse or compare rather than compute portfolio performance metrics.

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 an explicit applicability condition: 'Use to analyze actual portfolio ledgers or current holdings and valuation data,' and follows with prerequisites (real transactions/holdings, a current valuation per holding, FX rates where currencies differ). What it lacks is sibling routing — it never says to use parse_portfolio_csv first to obtain the ledger, or that compare_investment_vehicles handles cross-vehicle comparison.

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