get_portfolio_summary

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: broker rows are fetched live into a local append-only ledger with no broker writes, values are in KRW at current spot, leveraged products use the daily multiple, and open crypto futures are carried at signed notional but excluded from totals. The '(slower)' note on realized P&L is a useful performance caveat as well.

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 first clause front-loads the scope, then each section gets one tight clause with no filler; the closing two sentences carry the no-write guarantee. Density is high but every sentence contributes distinct information for section selection or trust calibration.

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 an output schema present the return shapes need not be restated, yet the per-section inventory adds selection value without becoming a schema dump. Safety (annotations + explicit no-write statements), currency, valuation conventions, and the slower-path caveat are all covered; only detail_level semantics are missing, which is minor relative to the whole.

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 0%, so the description must carry parameter meaning, and it does so thoroughly for 'sections' — each enum value is defined with its contents (NAV bridge, HHI, look-through exposure, ledger-sourced realized P&L). 'detail_level' ('summary' vs 'full') is never mentioned anywhere, which is a real gap given zero schema coverage.

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 opening line states a specific resource and scope: whole-portfolio totals across every broker account, decomposed by section. The four section names are enumerated with what each returns, so an agent knows exactly what capability this represents and can distinguish it from sibling holding/return tools.

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 supplies the default section pair (totals + realized) and marks 'realized' as '(slower)', which is actionable cost guidance for choosing sections. It also clarifies the tool never writes a snapshot, implicitly steering write-intent callers to snapshot_portfolio_nav. However, no sibling is named explicitly and there is no stated when-not-to-use condition.

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