Agent Financial Advisor

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

With no annotations, the description carries the full burden and does well: it discloses the internal orchestration (five sub-checks on the sections supplied), a critical safety guarantee ('never overrides a failed check'), and precise billing behavior including price, credit/x402 payment, and the first-memo-free exception. It leaves gaps around what happens when no section objects are supplied (all six params are optional) and around latency/output delivery.

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 and outcome, then orchestration, then the safety constraint, then pricing — a sensible order. The pricing sentence is dense and repeats 'paid only' twice, a minor redundancy, but nearly every clause carries information an agent needs.

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 six-parameter, nested-object, no-output-schema tool with zero annotations, the description covers what it does, what it returns (a memo with risks, exact changes, applicable rules, dated audit note), and the payment model. The notable omission is guidance for the all-optional case — an agent cannot tell whether calling with no sections is valid.

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 the baseline is 3. The description adds a little beyond the schema by explaining that checks run 'on whichever sections you send', clarifying that the section objects are optional and selectively executed, but it gives no additional detail on the nested request shapes beyond pointing at the sibling tool names.

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 — send a trade/options/portfolio, get a written decision memo — and enumerates the three possible verdicts (proceed, proceed with changes, do not proceed) plus the memo's contents. It also names the sibling checks it composes (pre_trade_check, position_size, tax_lot_plan, options_risk_check, portfolio_review), so an agent can tell this aggregator apart from the individual check 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?

Makes clear this is the tool for a consolidated written decision covering whichever sections you send, implicitly routing single-check needs to the named siblings. It also surfaces the cost gate (paid only, first memo per API key free, daily free calls and anonymous trial excluded), which is decision-relevant usage context. It stops short of an explicit 'use X instead when you only need Y' statement.

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

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

With no annotations at all, the description carries the full burden and does well: it discloses cost model (25 free calls/day, then prepaid credits), that the key is auto-attached to the current session, and persistence/auth mechanics for later sessions. It does not say what happens on repeat invocation (new key issued? old revoked?) or whether an existing key causes an error, which is a notable gap for a mutation with zero annotation coverage.

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?

Four compact sentences, each earning its place: value proposition, core action and side effect, invocation trigger, and post-call auth instructions. The call trigger and session-attachment behavior are front-loaded rather than buried.

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?

A one-optional-parameter tool with no output schema and no annotations needs exactly this: what it does, what it costs, what side effect it has on the session, when to invoke it, and how to reuse the result. Nothing an agent needs to call it correctly 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 description coverage is 100% for the single optional 'label' parameter, so the schema already explains it fully. The description adds no parameter-level guidance beyond generic behavior, which matches the baseline of 3 when the schema does the heavy lifting.

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 and resource ('Creates an API key for this agent') and adds scope details (attached to this MCP session, auto-used by subsequent calls). Despite the 'get_' name prefix implying a read, the text immediately makes clear this is a creation operation, and it is unmistakable versus every sibling (risk/portfolio/tax 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 gives an explicit trigger condition: 'Call this when the anonymous trial runs out.' It also tells the agent what to do after the call for future sessions (save the key, add ?key= or Authorization header). It stops short of stating a when-not condition or naming an alternative path, so it lands just below the top mark.

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

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

With no annotations, the description carries the full burden, and it does meaningful work: it discloses that the call is free, that quota is daily and resets (giving the temporal semantics of the counter), and that the free advisor_memo is a one-time allowance. It does not state whether this call itself decrements quota or what the response shape is, and no output schema exists to cover that.

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?

A single sentence, front-loaded with the most decision-relevant fact ("Free.") and then a clean enumeration of everything returned. No filler, no restating of the title.

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 zero params, no annotations, and no output schema, the description reasonably substitutes for the missing return documentation by listing the fields the agent will get back. The remaining gap is relational: it never positions itself against get_api_key, leaving the agent to infer which key-related tool answers which question.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a parameterless, context-derived call by talking only about "the API key" the agent is already authenticated with.

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 ("Shows") and an exhaustively enumerated resource: free calls remaining today plus reset time, prepaid credit balance, free advisor_memo availability, and how to add credits. The enumerated fields make it unmistakably the account/billing-status tool rather than any of the analysis siblings (advisor_memo, portfolio_review, get_api_key).

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?

"Free." signals this call costs nothing and implicitly tells the agent it is safe to call for status checks, and the field list implies the situations it answers. However, there is no explicit when-to-use clause and, notably, no differentiation from the sibling get_api_key, which an agent could plausibly confuse with this tool for key-related questions.

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

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

With no annotations, the description carries the full burden and does well: it enumerates the checks performed, names FINRA Rule 4210, and states the return contract (approve / approve_with_warnings / reject with reasons). It omits whether the call is read-only with no side effects, whether authentication or an API key is required, and any rate-limit behavior, which keeps it from a 5.

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 a single dense paragraph that front-loads the purpose and then lists checks, the return contract, and pricing. It is appropriately sized and largely waste-free, though the long checklist of checks could be structured more cleanly.

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 computational tool with nested inputs, no output schema, and no annotations, the description gives a strong conceptual account of what is evaluated and what the return statuses mean. It still leaves the agent without parameter-level guidance on required fields, policy overrides, and side-effect/auth expectations, but the core contract 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 description coverage is only 40%, so the description must compensate more than it does. It conceptually maps some inputs to checks (ex_dividend_date to assignment risk, account type to cash limits, options_level to approval level), but it never explains the legs structure, the required/optional distinction, or the policy override object, so meaningful gaps remain.

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 states a specific verb and resource: check an options book (existing or proposed legs) for margin, cash-account limits, assignment risk, pin risk, exercise, max loss, and Greeks. It is unmistakably an options risk/margin tool, but it does not explicitly name or distinguish itself from overlapping siblings such as pre_trade_check or suitability_check, so it falls short of a 5.

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 implies usage by saying it can check 'existing or proposed legs,' which covers both post-trade review and pre-trade evaluation. However, it gives no explicit when-to-use guidance versus alternatives like pre_trade_check or position_size, nor does it state prerequisites or exclusions.

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

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

With no annotations, the description carries the burden and does reasonably well: it discloses the price ($0.05), the conditional dependency (risk stats require return history), and the output shape ('ends with prioritized findings'). It does not state that the operation is read-only/non-mutating or what happens with missing sectors/targets, which keeps it below a 5.

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?

A single dense but well-ordered sentence puts the core outputs first, followed by conditional metrics and the closing 'prioritized findings', with price appended last. It is long but nearly every clause names a distinct output; only the price tag sits as a slightly detached addendum.

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?

There is no output schema, and the description compensates by enumerating the returned analyses, which is a real strength given the nested holdings objects and 9 parameters. Still, key input semantics (benchmark for beta, limits for concentration flags, periods_per_year annualization) are left undocumented, so an agent cannot fully specify a correct call from this description alone.

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 33% across 9 parameters, so the description must compensate and largely does not. It links 'returns' to the risk metrics and implicitly links 'targets' to drift, but says nothing about 'limits' (max_drawdown/max_sector_weight/max_single_weight), 'benchmark_returns' (which is what beta must consume), 'cash', or 'periods_per_year' — an agent could easily call it without a benchmark and get no beta.

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 ('periodic advisor review of a portfolio') and enumerates exactly what is computed: weights, HHI/effective holdings, sector and asset-class exposure, drift with rebalance trades, and the return-based risk metrics. No sibling tool (advisor_memo, strategy_audit, suitability_check) has this scope, so the agent can distinguish it 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?

Usage is implied by 'periodic advisor review' and by the conditional 'given return history', which tells the agent that risk metrics only materialize when returns are supplied. However, there is no explicit guidance on when to pick this over advisor_memo or strategy_audit, and no exclusions or prerequisites stated.

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

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

With no annotations, the description carries the full burden: it does disclose that a max-position cap and round lots are applied and that the result explains the binding constraint, which is useful beyond the schema. It omits what the tool returns in concrete terms (shares vs notional), how invalid or conflicting inputs are handled, and any authentication requirements, though the stated $0.005 price gives partial cost context.

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?

Two tight sentences, front-loaded with the core action and method list, followed by applied constraints and the price. Every clause is informative, though the trailing price mention is slightly promotional in placement.

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 17-parameter tool with no output schema and no annotations, the description is adequate but thin: it never states which parameters are conditional on which method, and allows an undocumented 'allow_fractional' plus unlabeled 'side'/'entry_price'. It does at least signal that the response includes a binding-constraint explanation.

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 71%, so the schema already explains most parameters including per-method fields. The description adds only the method vocabulary and the cap/round-lot behavior, leaving per-method required inputs (e.g. stop_price for fixed_fractional, win_rate/avg_win/avg_loss for Kelly) for the agent to infer from individual field descriptions.

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 uses a specific verb and resource ('size a position') and enumerates the three supported methods (fixed-fractional, volatility targeting, fractional Kelly), so an agent knows exactly what computation it performs. It does not explicitly contrast itself with siblings like pre_trade_check or options_risk_check, which keeps it off the top mark.

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?

Method choice is implicitly signposted by naming the inputs each method relies on ('risk to a stop', 'ATR or annualized vol', 'fractional Kelly from your edge statistics'), which hints at when each applies. However, there is no explicit when-to-use/when-not-to-use guidance and no routing to sibling tools for pre-trade or suitability checks.

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

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

With no annotations, the description carries the burden and does well: it discloses the return vocabulary (approve / approve_with_warnings / reject with reasons), that a resized quantity may come back, and even the $0.005 cost. It never explicitly says the tool is read-only and does not itself transmit the order, which is the one thing an agent could misread from "run an order past."

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?

Three front-loaded sentences: what it does, what it checks, what comes back plus cost. The long middle checklist is dense but every item maps to a real rule dimension, so nothing feels padded.

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 multi-object, nested-input risk engine with no output schema, the description is strong: it names the decision outcomes and the resizing behavior, which is what the agent most needs to interpret results. It stops short of clarifying whether market data is optional or what happens when it is omitted, and never confirms the tool is side-effect free.

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 50%, with four top-level objects (order, market, policy, account) and nested items. The description implicitly signals relevant inputs — stop price for risk-per-trade, recent_sales for wash sales, buying power, settlement, market hours — but never mentions the market or policy objects or the effect of policy overrides documented in 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?

Specific verb and resource: run an order past a compliance/risk check before it reaches the broker, followed by an enumerated list of the exact checks performed. That enumeration makes it clearly distinguishable from neighbors like options_risk_check or suitability_check, though no sibling is named explicitly.

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?

"Run an order past ... before sending it to the broker" establishes the workflow slot precisely: this is a pre-submission gate, not a post-trade review. It does not state when to skip it or which sibling to use instead (e.g. for options orders), so the routing guidance is contextual rather than explicit.

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

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

With no annotations, the description carries the full burden and does disclose meaningful traits for a reference tool: currency of data, inclusion of effective dates and sources, and that content may postdate the model's training (concrete example: June 2026 PDT replacement). It does not state whether the tool is read-only or whether there are size/pagination limits, but for a static lookup the recency disclosure is the trait that matters.

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?

'Free.' opens the description and 'Price: free.' closes it, restating the same non-behavioral fact twice. The middle content is dense and useful, but the duplicated pricing line is filler that the 10%-weighted conciseness dimension cannot ignore.

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?

Coverage areas and data freshness are covered, which is most of what a caller needs. However, with no output schema and no parameter documentation, the description never says what the returned digest looks like or how the optional topic filter scopes it, leaving gaps for a one-parameter tool.

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 0% and the single 'topic' parameter is never mentioned in the description — not its purpose, not that it is optional (required=0), and not what happens when it is omitted. The enum values are self-explanatory but the description adds nothing to compensate for the total coverage gap.

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 clearly identifies the resource: a digest of current US trading, margin, settlement and tax rules, with effective dates and sources. That distinguishes it from the sibling action/check tools (pre_trade_check, suitability_check, options_risk_check), though it never names them. Purpose is clear but the retrieval verb is only implied.

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?

Usage is only implied by 'rules an agent must follow' and the note that it covers changes predating training data. There is no explicit statement of when to prefer this digest over siblings like pre_trade_check or strategy_audit, and no mention of when it should be skipped.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose the return shape ('a verdict and red flags'), the computational method (t-stat, PSR, Deflated Sharpe correcting for n_trials) and the cost ($0.1) — details absent from structured fields. It stops short of confirming the operation is read-only/non-mutating or noting any rate limits or failure modes.

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?

Three dense sentences, front-loaded with the purpose, then the outputs, then the differentiator (deflated Sharpe) and cost. Every sentence earns its place, though the metric list is long enough to read as enumeration rather than guidance.

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 no output schema, the description must convey what comes back, and it does in one phrase ('a verdict and red flags') but gives no sense of the verdict's form or severity levels. It also doesn't clarify that at least one of trades or returns is effectively needed despite zero required parameters, which is the main practical gap for a 6-parameter tool.

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 83%, so the schema already documents most parameters. The description hints at the meaning of n_trials ('corrects for how many variants you tried') but adds no format or input-preparation guidance beyond that, so baseline 3 applies.

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 ('independent performance auditor for a trading strategy or backtest') and enumerates the exact statistics computed, so an agent can distinguish it from portfolio_review or options_risk_check without opening the schema. The scope boundary of auditing a backtest's edge rather than reviewing a live portfolio is explicit.

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?

Usage is implied by 'From a trade list and/or periodic returns' and by the overfitting framing, which tells the agent this is for post-backtest validation. However, it never states when NOT to use it, nor does it name an alternative sibling for related tasks (e.g., portfolio_review for live portfolios).

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

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

With no annotations, the description carries the burden and does reasonably well: it discloses that the output is a timestamped, hashed suitability memo for the audit file, that complex products get flagged, and that the call costs $0.03. It does not say whether inputs are stored/retained, what happens on a failing check, or the failure mode for malformed data.

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?

Purpose is front-loaded in the first clause, and the remaining content (what is compared, what is flagged, what is returned, price) all earns its place. The single long sentence is dense but not padded.

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 nested-parameter, no-output-schema, no-annotation tool, the description covers the return artifact and the comparison axes but leaves the two omission-related parameters (annual_fee_pct, max_single_position_pct) and error/retention behavior unexplained. Adequate but with clear gaps given the tool's complexity.

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?

At 60% schema coverage the description adds useful framing for the client factors (age, horizon, risk tolerance, liquidity need, experience) and the products list, mapping them to the review logic. However annual_fee_pct, max_single_position_pct, net_worth and annual_income get no explanation in either the description or fully in the schema, so the gap is only partly closed.

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: a pre-recommendation compliance/suitability review that compares a proposal against client attributes under Reg BI, plus a memo artifact. It is clearly distinct from generic siblings like portfolio_review or pre_trade_check in scope, though it never names an alternative to route against.

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?

"should run before recommending a portfolio to a person" gives a clear triggering condition and ordering. There is no explicit when-not guidance and no named alternative among the sibling tools (e.g., pre_trade_check, options_risk_check), so it stops short of full routing guidance.

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

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

With no annotations, the description carries full burden. It does add real value: it enumerates what the tool computes (gain splits, tax estimates, wash-sale flags, lots about to turn long-term) and discloses pricing ($0.02). It never states that this is a pure advisory/computation tool with no execution side effects, which matters because the phrasing 'for a sale' could lead an agent to believe it places one.

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 core capability and the harvest variant are front-loaded, and the $0.02 cost note is short and last. The middle sentence is a long comma-separated list, but each item is a distinct output an agent would want, so little waste.

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 9-parameter, nested-object tool with no annotations and no output schema, the description covers the analytical scope well but leaves the return shape implicit and does not clarify that supplying lots/sell is required for the sell mode. An agent could call it but would be guessing about the response.

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 only 44% across 9 parameters, so the description must compensate. It partly does — 'mode=harvest' maps to mode/as_of/prices, 'estimates tax' maps to tax_rates, 'flags wash sales' hints at recent_transactions — but the required 'lots' array structure and the symbol parameter are never explained beyond the example.

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 states a specific verb and resource — compare FIFO/LIFO/HIFO/minimum-tax lot selection, split short/long-term gains, estimate tax, flag wash sales — which is far more than a restatement of the name. It does not, however, say how it differs from near siblings like pre_trade_check or suitability_check, so the boundary is left to inference.

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 explicitly distinguishes the two modes: the default 'sell' path is a tax advisory comparison for a sale, and 'mode=harvest' scans positions for tax-loss harvesting. That gives an agent a clear condition for each branch, but no exclusions against alternatives or prerequisites (e.g., must lots be supplied before any sale proposal).

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