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

Annotations declare a safe read-only, closed-world operation, and the description adds substantial context beyond them: the solution is long-only, budgets are normalized internally rather than required to sum to 1, zero/negative variance and non-finite inputs are hard errors, and risk contributions should match budgets at convergence. The explicit "not covered" list preempts false expectations about leverage and weight bounds.

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 core computation before edge cases, and the error conditions are compressed into a single dense but readable sentence. Minor waste: "Long-only weights" appears twice (once in the opening clause, once as a standalone fragment), and the returns sentence partly duplicates the parameter docs.

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?

Despite no output schema, the description enumerates the return values (weights, risk_contributions matching budgets at convergence, portfolio_volatility), and all three inputs are covered with minimum-size and validity rules. Nothing an agent needs to call this correctly — input form choice, error conditions, output shape — is missing.

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 would be 3, but the description adds real meaning: at least 2 assets, each series at least 2 values of identical length, covariance must be square and 2x2 or larger, and the two inputs are mutually exclusive ("never neither"). Risk budgets must be positive and finite and are normalized. It adds the either/or exclusivity and minimum-size constraints that the bare schema does not enforce.

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 — computing risk-parity portfolio weights from a covariance matrix or return series, with equal or custom risk contributions. It is clearly distinguishable from nearby siblings such as workflow.run_portfolio_risk or workflow.run_kelly_frontier because it names the exact optimization target (equal risk contribution) and the long-only constraint.

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 explicit when-to-use phrasing with example user questions ("what weights give each asset equal risk contribution?") and an explicit scope exclusion set (shorting, leverage, weight bounds, transaction costs, covariance estimation error), plus a note that this is a calculation, not a recommendation. It never names a sibling tool as the alternative path, so routing between overlapping portfolio tools is left to inference.

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