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

Goes well beyond the annotations: it discloses the proxy-bypass fetch path, the live-probe validation that rejects non-feed URLs, the idempotent return-existing behavior (consistent with idempotentHint=true), and the list cap. These are real operational traits an agent cannot infer from readOnlyHint/destructiveHint alone.

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-loads the action, then constraints, then the trigger phrase. Every sentence carries a distinct fact (validation, idempotency, cap) with no padding.

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?

Covers validation/failure behavior, idempotency and the growth cap; an output schema exists so return-value detail is unnecessary. Nothing an agent needs to call this 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 coverage is 100% and both params are already described, but the description adds non-obvious constraints not in the schema — the URL must be http(s) on a public host and must parse as a feed. That meaningfully sharpens how 'url' should be supplied.

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 precise verb+resource ('Add an RSS/Atom feed to the crawler's source list'), which is clearly distinct from siblings news_sources and remove_news_source. An agent can tell exactly what this creates 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?

Provides explicit trigger phrasing ('Use when someone says "follow <site>'s news" / "加个新闻源"'), which grounds when to call it. It stops short of naming alternatives or when-not conditions (e.g., listing via news_sources, removal via remove_news_source), so it is clear context but not 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write/cash impact is partly covered. The description still adds real value beyond them: it is pure bookkeeping (no real orders are placed), it moves ledger cash, it requires user confirmation first, and it discloses the fund-settlement distortion. It does not cover edge cases like failure modes when cash is insufficient, but with annotations carrying the safety profile this is strong.

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 prose is front-loaded with purpose and the routing caveats before the Args listing, and the Returns line is brief because an output schema exists. The Args section, however, duplicates the input schema nearly verbatim, which is expendable length even though each individual sentence is well-formed.

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 an 8-parameter write tool with an output schema, the description covers everything an agent needs: what it does, what alternatives exist for the two important edge cases, the confirmation prerequisite, the gold special case, and idempotency on retry. Nothing material is left unstated.

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 Args block is largely a restatement of the schema's own parameter descriptions (gold ticker/units/currency, idempotency reuse, unit_label default). It adds minor framing value, such as tying `currency` omission to the existing position, but nothing the schema does not already say.

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 sentence names a specific verb and resource — 'Record a buy in the local ledger' — and immediately explains both branches (weighted-average add to an existing position, or new position for an unseen symbol). It also states what the tool is not: 'openInvest never places real orders,' which sharply separates it from a real brokerage order path.

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 explicit routing rules: pre-existing holdings go to `record_existing_position`, off-exchange China mutual funds go to `place_fund_order` + `confirm_fund_order`, and it explains why (buy would book them as instantly filled, distorting totals). It even specifies a pre-call obligation — confirm symbol, units, and price with the user — which is actionable usage guidance, not just context.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantive context: the amount returns to ledger cash, the side effect touches ledger cash so user confirmation is required, and the error return shape is disclosed. It stops short of covering idempotency or failure-recovery behavior, keeping it short of 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?

Scope, preconditions, and the alternative are front-loaded in the first two sentences, before the Args/Returns blocks. The Returns section partially duplicates the existing output schema, which is minor waste, but the overall structure is clean.

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 destructive tool with an output schema already present, the description covers the state precondition, the side effect, the alternative tool, and the error case. Any remaining gaps are minor and would be covered by the output schema.

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% and the schema already explains that order_id is an in-transit order with status 'placed'. The description's 'The in-transit order to cancel' adds no meaning beyond that, so it sits at the baseline for a schema-documented parameter.

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 ('Cancel an in-transit off-exchange fund order') with a precise qualifier ('that was never executed'). It explicitly distinguishes itself from the confirm/sell siblings by noting that confirmed orders hold shares instead.

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 precondition ('Only orders still in transit can be cancelled'), names the alternative path for confirmed orders ('use `sell` to book a redemption'), and adds an operational directive ('Confirm with the user before calling'). Nothing 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.

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

The description says the tool is 'Safe to call twice' and that an already-confirmed order changes nothing, which is idempotent behavior, but annotations declare `idempotentHint: false`. It also frames the operation as safe/idempotent while `destructiveHint: true`, creating a direct annotation contradiction despite otherwise useful behavioral detail.

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 and the automatic-job caveat are front-loaded, and the edge-status details earn their place. However, the Args and Returns blocks duplicate schema/output-schema content, making it slightly longer than necessary.

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 state-changing financial operation, the description covers purpose, manual-use conditions, duplicate-call behavior, pending NAV, fee/NAV semantics, and status returns. An output schema exists, so detailed return-shape explanation is not needed; completeness is strong.

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 schema already documents `order_id`, `nav`, `fee`, defaults, and the pending-NAV behavior. The description's Args section largely restates those fields, adding little beyond the units formula already present 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?

Names the exact operation and accounting effect: turning an in-transit fund order into shares at the pricing day's NAV. It clearly positions itself as the second leg after place_fund_order and is distinguishable from place_fund_order and cancel_fund_order.

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?

Explicitly says the `fund_confirm` job runs automatically every weekday evening and manual calls are only for supplying NAV/fee or confirming early. It also gives conditions for duplicate calls and unpublished NAV.

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?

Goes well beyond annotations: agent mode only reads today's submitted verdicts (nothing re-run), backend mode runs the committee itself, requires a backend LLM key, and takes minutes. It also discloses the `missing_verdicts` failure semantics. These auth, latency, and side-effect details explain why readOnlyHint=false and are exactly the context an agent needs.

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 sentence and every subsequent sentence carries load-bearing workflow or failure information. Slightly dense (backticks, arrows, mode labels) and the bare "roles" step is ambiguous, but there is no filler to cut.

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, return values need not be re-explained, and the description covers the mode split, prerequisites, key requirement, latency, and failure handling. Nothing an agent needs to invoke this correctly is absent.

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 to disambiguate; baseline 4 applies. No parameter meaning is missing because the schema is empty.

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 ("Assemble") and resource ("today's daily report") and enumerates the report's contents (portfolio, verdicts, performance, holdings digest), plus the return artifact (`full_report` Markdown). This clearly distinguishes it from siblings like decisions, run_committee, and status.

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?

Explicitly separates two operating modes and gives the exact precondition for agent mode (run prepare_committee → roles → submit_committee for every target asset FIRST) versus backend mode. It also tells the agent what to do with `missing_verdicts` entries (treat as failure and report). No inference required.

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?

Annotations only declare readOnlyHint=true, and the description's 'Read-only' line merely repeats that. The genuine added value is behavioral: the list is capped at `limit` newest-first so a year of history doesn't flood context, while `count` and `summary` still cover every match — a non-obvious pagination/aggregation contract the agent would otherwise have to guess.

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 resource and its purpose, then use cases, then args and returns in clearly labeled blocks. The Returns block is partly redundant given the output schema exists, but the structure is scannable and every other sentence earns its place.

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 four-parameter, zero-required read tool with a full output schema, nothing needed to invoke it correctly is missing: the agent knows the default window, the cap semantics, how to filter, and that aggregates cover all matches. Return-value detail is arguably redundant but not a gap.

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 largely restates the schema (default 90 days, limit 0 = all, case-insensitive symbol, verdict examples) and adds only the 'newest first' ordering and the rationale for the cap, which is modest incremental meaning.

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 resource (the unified decision ledger) and enumerates its composition — committee verdicts joined with rule interventions, executions/refusals with reasons, and outcome data — plus an adoption-rate summary. This is clearly distinguishable from siblings like `history`, `discipline`, and `explain_decision`, which an agent can rule out from the text alone.

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 concrete usage contexts via the quoted questions it answers ('how often did I follow the advice', 'which recommendations did I skip') and tells the agent to use `symbol`/`verdict` for single-asset or single-verdict questions. It never explicitly names an alternative tool or states a when-not condition, so it stops short of a 5.

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?

Annotations already mark this as a non-read-only mutation, and the description adds important context beyond them: no real payment system is connected, idempotency-key retry behavior is documented, and return behavior is summarized. It does not fully address the destructiveHint annotation or discuss reversibility/permissions, so it is strong but not complete.

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 front-loaded with purpose and scope, then uses short Args/Returns sections. It is appropriately sized, though the Args and Returns sections partly duplicate the input and output schemas.

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?

Given the tool’s complexity, rich input schema, existing annotations, and output schema, the description provides everything an agent needs: it clarifies bookkeeping-only behavior, amount/currency expectations, idempotency retry semantics, and error/return shape at a high level.

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 schema already explains currency format, amount constraints, and idempotency-key behavior in detail. The description’s Args section largely mirrors that information rather than adding substantial new semantics, making the baseline 3 appropriate.

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: “Record a cash deposit into the ledger,” and clarifies scope with “in any currency” and “Bookkeeping only.” This is clearly distinguishable from sibling tools like withdraw, buy, or record_fee.

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 provides useful context that this is bookkeeping-only and not connected to a real payment system, which implies when it should be used. However, it does not explicitly name alternatives or state when not to use this tool versus withdraw, buy, or other ledger mutation tools.

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?

Annotations already declare readOnlyHint=true, so description adds value by detailing return structure (summary + markdown) and the specific metrics computed. Does not contradict annotations.

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 sentences with zero waste. Front-loaded purpose, then usage, then return structure. Every sentence adds value.

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?

Given zero parameters, read-only annotation, and existence of an output schema, the description fully explains what the tool returns and its purpose without needing more detail.

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?

No parameters in input schema (100% coverage), so baseline is 4. Description does not need to add param info; it correctly focuses on behavior and return format.

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?

Description clearly states the verb 'Get' and resource 'discipline ledger', specifying exact metrics (HOLD ratio, intercepted trades, money saved/lost). Distinguishes from siblings like 'decisions' and 'explain_decision' by focusing on blocked interventions and counterfactual value.

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?

Explicitly tells when to use: when user asks 'what has the committee blocked' or 'is this tool actually helping'. Also marks as 'Read-only', which implies it should not be used for modifications.

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?

Annotations declare readOnlyHint=true, and the description adds value beyond that: it discloses a side effect ('makes one short HTTP probe to the configured LLM endpoint when a key is set') and explains the nuanced readiness semantics (optional_for_coordinator / optional_for_email, coordinator vs direct path). This is rich behavioral context not available from annotations.

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 purpose is front-loaded in the first sentence, and the remaining content is dense but mostly earns its place. The closing 'Returns:' block is somewhat redundant given an output schema exists, costing a little conciseness.

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 zero-parameter, read-only health check with an output schema, the description covers everything an agent needs: when to call it, how to interpret `status`, the optional-check semantics, and the probe side effect. Nothing essential 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?

The tool takes zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description correctly does not fabricate any.

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 resource and action — a session health check — and equates it to `run.sh doctor` for agents without shell access. It clearly distinguishes itself from siblings by defining what `status` values mean and what the tool's overall job is.

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 states explicitly that this is 'the first call of a session' and when to hand over to the `invest-setup` skill (`needs_setup`). It also clarifies that missing LLM key/mail credentials do NOT trigger `needs_setup`. It does not explicitly differentiate from the sibling `status` tool, but the usage context is clear.

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?

readOnlyHint already covers the safety profile, but the description adds meaningful behavioral context: which return fields to surface to the user (confidence_lookup over the raw confidence, transcript_markdown rendering) and that path_snapshot may be null. This goes beyond the annotation.

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 purpose sentence followed by clearly labeled when-to-use, Args, and Returns sections makes it easy to scan. It is somewhat verbose and the decision_id format is repeated in both Args and the schema, but every section carries useful signal.

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 tool returning a complex multi-part object, the description supplies enough to invoke and interpret it, and an output schema exists as backup. Coverage of invocation, usage, and return handling is solid, though naming a sibling for the 'list decisions' case would fully close the loop.

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% and the schema already documents the decision_id format and example. The Args section largely restates that same '<date>/<symbol>' format, so the description adds little beyond the structured field. 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: retrieve the full reasoning behind one committee verdict, enumerating the concrete artifacts (4-role debate transcript, CIO memo, path-probability snapshot). This clearly distinguishes it from sibling tools like decisions (list) and run_committee (execute).

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 concrete trigger phrasings ('why was today's verdict HOLD') and the audit scenario, which tells the agent exactly when to reach for it. It doesn't name a specific alternative tool or a when-not condition, so it falls 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?

Annotations already declare readOnlyHint=true. The description adds the read-only label and details the return structure (trades with specific fields and committee verdict records), providing useful behavioral context beyond the annotation.

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 concise and front-loaded with the main purpose. Every sentence adds value, and the docstring style for Args and Returns is well-structured without redundancy.

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?

Given the tool's simplicity (one optional parameter, no nested objects) and the existence of an output schema, the description is sufficiently complete. It outlines what is returned without needing to detail the schema.

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% with the parameter 'n' already described as 'Maximum number of recent trades to return.' The description repeats this and adds no additional semantics, so it meets the baseline for high 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 description clearly states the tool retrieves 'the most recent trade records and committee verdict history.' It uses a specific verb ('Get') and resource, and distinguishes itself from siblings like 'live_prices' or 'status' by focusing on historical data.

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 explicitly provides usage context with example queries like 'what did I buy recently' and notes it is read-only. It does not explicitly mention when not to use or suggest alternatives, but the context is clear.

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?

Goes well beyond the annotations: it explains that the tool requires a backend LLM key, is disabled in advisory mode, is idempotent over url/claim, and that a new holding-relevant event can trigger a rate-limited committee re-run whose id is returned as 'queued:<id>' awaiting the agent in pending_committees. That is rich, decision-relevant behavioral 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?

Front-loads the core action and the preferred invocation path, then organizes detail into Args and Returns sections. It is long, but for a 12-parameter ingestion tool with mode gating and an error path, nearly every sentence carries weight; a few clauses are mildly redundant with the schema.

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?

Complete for the tool's complexity: it covers the preferred vs. fallback normalization, key requirement, idempotency, mode gating, error behavior, and the committee-trigger return semantics, so an agent can call it correctly and anticipate outcomes without reading the output schema.

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 the baseline is 3, but the description adds cross-parameter meaning the schema does not: the stance/severity/one_line_claim coupling and the preferred self-normalization bundle, plus the provenance distinction between ingested_by and source and the url-as-dedup-key role. It does not tie every parameter together, keeping it just below top marks.

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 (feed/ingest) plus resource (finance news item) and the full downstream effect: graded, mapped to affected symbols, stored for committee RAG recall. It is clearly distinguishable from siblings such as news_sources, pending_news, and the committee 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?

Gives explicit when-to-use guidance (proactively feed news the self-hosted crawler misses, especially A-share/regional coverage) and names the alternative normalization path (self-normalize vs. rely on the backend model), including the failure mode when keyless. Exclusions are stated too: disabled in advisory mode.

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?

Annotations already establish readOnlyHint=true, and the description reinforces this ('Read-only; single batch, no arguments') rather than contradicting it. It adds genuine behavioral context beyond annotations: the fixed-instrument scope and the null-field semantics when an upstream quote is unavailable. It stops short of stating freshness/latency guarantees, so not quite 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?

Purpose and routing constraint are front-loaded in the first paragraph, which is ideal. The trailing 'Returns' block enumerates every key and duplicates what the output schema already documents, making it the one part that doesn't fully earn its space.

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 zero-argument read-only tool this is complete: scope, sibling routing, read-only guarantee, batch behavior, and null handling are all covered, and an output schema exists to carry the return structure. 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?

Zero parameters, so the baseline is 4. The description correctly states 'no arguments', which is consistent with the empty schema and leaves nothing ambiguous for the caller.

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 (Fetch) and a precise, enumerated resource (spot gold, USDCNY/AUDCNY FX, NDQ.AX, VIX, TNX) as a fixed reference set. It also explicitly distinguishes itself from the sibling `status`, which covers the user's own positions. An agent can route correctly without opening any 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?

Gives explicit when-to-use (quick market context before analysis; user asks 'how is the market / what's the gold price') and an explicit when-not, naming the alternative tool (`status`) for user-held positions with the condition that selects it. No inference required.

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?

Annotations already declare readOnlyHint=true. Description adds context about built-in vs extra feeds and mentions related mutating tools, which is helpful but not extensive.

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 sentences, front-loaded with the core action and resource, no redundancy. Every sentence adds value.

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 and zero parameters, the description fully explains what the tool returns (list of sources with types). No gaps.

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?

No parameters exist; schema coverage is 100% (empty). Description correctly omits param details, as none are needed.

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 the verb 'list' and resource 'news feed sources', clearly distinguishing between built-in defaults and user-added extras. References sibling tools add_news_source and remove_news_source to differentiate.

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?

Explicitly says when to use: when someone asks 'what news sources do you follow' or before adding/removing a source. Provides clear context for invocation.

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?

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false; the description usefully adds the 24h request expiry and the rule for when an item is considered done. However, it never explains why the tool is flagged non-read-only (does calling it claim or consume items?), leaving a real behavioral gap against its own annotation.

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 tight sentences with no filler, and the workflow instruction is front-loaded after the purpose. The opening sentence is a dense fragment with an awkward line break, which slightly hurts immediate parseability, but nothing is wasted.

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 parameters and an output schema present, the description does not need to describe return values, and it supplies the mode, workflow, completion rule, and TTL an agent needs to service the queue. The only missing piece is whether invoking it mutates state, which matters given readOnlyHint=false.

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 the schema imposes no semantic burden and the baseline is 4. There is nothing about arguments the description could or should clarify.

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 identifies the resource (pending committee re-runs) and its trigger conditions (requested by events or price moves) and the operating mode (agent mode). It is a fragment rather than a verb-led statement, but an agent can tell it is the queue of committee work items it must service. It stops short of naming a sibling like run_committee to sharpen the contrast.

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 follow-up procedure: for each item run `prepare_committee`, then the roles, then `submit_committee`, plus the completion condition (a newer verdict for that symbol) and the 24h expiry. What it does not state is when to call this tool itself versus run_committee or pending_news, so routing guidance is inferred 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds real context beyond that: the queue-draining behavior, the 48h expiry, and the fact that dismissal permanently suppresses the URL. It doesn't explain pagination or ordering, but the mutation and lifecycle semantics are well disclosed.

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-loads the purpose, then gives the per-item workflow in one compact thought. Efficient and well ordered, though the path-like parameter listing (`one_line_claim` / `stance` / ...) is slightly dense.

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?

An output schema exists, so return values need not be described. Together with the annotations, the description covers the workflow, the sibling handoff, the queue lifecycle, and the expiry window — everything needed to call it correctly.

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 both limit and dismiss_urls are already documented. The description reinforces the intent of dismiss_urls (irrelevant items passed back), which is marginal added value over the schema's own 'they won't be offered again'. Baseline 3 is appropriate 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?

States a specific resource (news the backend fetched but did not normalize) and the reason it exists (reasoning is delegated to the agent). It is distinguishable from ingest_event and the other news siblings by scope: this is the raw intake queue, not the ingestion or source-management tool.

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?

Explicitly routes the agent: call ingest_event for relevant items, pass irrelevant ones back as dismiss_urls. It also states the lifecycle condition (items leave the queue once ingested or dismissed, expire after 48h), so when-to-use and when-it-disappears are both answered.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true) by spelling out the actual ledger effect: cash is deducted now, the in-transit amount counts at face value so total assets don't move and there is no fake dip. It also discloses the confirm-date calendar limitation (Monday–Friday, no China holiday table), the lag_source, and the idempotency-key retry semantics, which is exactly the kind of side-effect detail an agent needs for a mutating tool.

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 ledger effect, then supporting caveats, then args/returns. Efficient for the amount of information conveyed, though the Returns block is partially redundant given an output schema exists.

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 mutating, non-idempotent bookkeeping tool with 6 params, this covers side effects, timing/NAV rules, confirmation workflow, retry semantics, and the sibling used to confirm. With an output schema present, the extra return-value summary is harmless and nothing an agent needs to invoke 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 coverage is 100% and the schema descriptions are more detailed than the description's Args block (e.g. the 15:00 NAV cutoff and the idempotency-key duplicate behavior live in the schema). The description restates symbol/amount/currency without adding format or edge-case meaning beyond what the schema already provides, 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 precise verb+resource ('record the first leg of an off-exchange fund purchase') and immediately draws the boundary that distinguishes it from siblings: 'Bookkeeping only — openInvest never places orders.' An agent can tell it apart from buy/confirm_fund_order/record_execution without opening a 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?

Gives clear when-to-use context ('the user already placed' the order, confirm fund/amount/time before calling) and names the alternative path for confirmation (the `fund_confirm` job or `confirm_fund_order`). It stops short of explicitly excluding the look-alike `buy` tool, so routing is good but not exhaustive.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses genuinely important behavior: the backend retains its own copy of the deterministic facts and reuses them at submit time (defense downgrade, regime, path snapshot) so omitted facts can't silently disable a rule, and the prepared data expires after 6 hours. This is exactly the kind of stateful/expiry/auth-adjacent context the annotations cannot convey.

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 step-by-step structure is front-loaded with the purpose and then the sequence, and each statement adds value. It runs a bit long with parentheticals, but nothing is truly wasted given the multi-step workflow described.

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 prep tool with no output schema, the description enumerates the returned payload (regime, sentiment/defense flag, valuation, macro, events, portfolio, path reference, the 6 role prompts, and instructions for the 3 rounds), which is exactly what an agent needs to proceed. Nothing essential 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% and there is a single well-documented parameter, so the schema already carries the semantics. The description adds no syntax or format guidance for `symbol` beyond what the schema states, making a baseline 3 appropriate.

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 opens with a precise verb+resource+scope: 'Step 1 of the agent-run committee (Coordinator path): get everything YOU need to play the 4 roles yourself.' It distinguishes itself from sibling paths by explicitly ruling out a 'backend LLM key' and by naming the follow-up tool submit_committee, so an agent can place it relative to run_committee and submit_committee immediately.

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 clear sequencing: run Macro/Quant/Risk subagents, write the CIO memo, then call submit_committee, plus a concrete 6-hour submission window. It never explicitly states when NOT to use it versus the alternative run_committee path, so the choice between the two coordinator/backend paths 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.

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

Adds substantial behavior beyond readOnlyHint: it places no order, makes no LLM call, explains target sourcing, equal-split fallback, lot-size rules, and return/error shape. This is rich context for a read-only planning tool.

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-loads what the tool computes and the key no-order boundary, then provides useful usage and return details. It is somewhat long, and the returns section is partly redundant because an output schema exists, but overall it is structured and mostly earns its space.

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?

Given the rich input schema, output schema, and readOnlyHint annotation, the description covers the remaining agent-relevant context: target allocation sourcing, lot-size constraints, human execution, no LLM call, and error returns. Nothing critical is missing for correct selection and invocation.

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% and both parameters already have detailed schema descriptions, including mode semantics, defaults, and band_pct range. The description repeats the mode/band basics rather than adding much parameter-specific meaning 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: compute a rebalance list against target allocation, with explicit scope that it only produces BUY/SELL/NONE recommendations and places no orders. This clearly distinguishes it from execution-oriented siblings such as buy, sell, and record_execution.

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 user-question triggers ('do I need to rebalance', 'how far am I from target', 'what should I buy/sell'). It also clarifies the human-execution boundary, though it does not explicitly name all relevant alternatives such as what_if for scenario analysis.

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?

Beyond annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description discloses rich behavioral detail: exactly how cash is credited, that positions are unchanged, that it counts as account return inside NAV, that it is bookkeeping-only and never moves money, that a non-held/ledger symbol is rejected, and how the idempotency_key produces a duplicate response on retry.

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 front-loaded: the core effect appears in the first sentence, followed by a confirmation directive, then an Args block and a brief Returns note. It is somewhat long because the Args section duplicates the 100%-covered schema descriptions, but the structure remains clear and each section is purposeful.

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?

Given the tool's complexity (10 parameters, mutation with ledger effects, idempotency, reinvestment, typo guard), the description covers all necessary context. An output schema exists, so the minimal 'Returns' line is sufficient without describing return values in detail.

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 schema already documents all ten parameters. The description largely restates those schema descriptions (e.g., amount > 0, tax_withheld formula, reinvest meaning) and adds only minor emphasis, so it does not meaningfully extend parameter semantics beyond the structured data.

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 first sentence states a specific verb and resource ('Record a dividend (or interest)') and immediately clarifies the accounting treatment ('credits ledger cash by amount - tax_withheld, positions unchanged'). It also distinguishes the action from a sibling concept by explicitly saying it 'counts as account return (inside NAV), not as a deposit.'

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 clearly scopes usage to dividends or interest 'the user already received' and adds a prerequisite ('Confirm symbol, gross amount, withholding tax, and the date with the user before calling'). It rules out deposit-like behavior and warns about the typo guard, but does not name or route to alternative sibling tools for other income events (e.g., record_return_of_capital).

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?

The description complements the annotations by explaining the idempotent behavior: 'replay the same record is a no-op, so retries are safe'. It also notes that the tool appends to the execution ledger and returns the stored record or error, providing full behavioral disclosure beyond the annotations' flags.

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 concise and well-structured: first sentence states purpose, then behavioral note, usage guidance, Args, and Returns. Every sentence serves a purpose, and the structure is easy to parse. No unnecessary words.

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?

Given the tool has 4 parameters (2 required), an output schema, and annotations, the description covers all necessary context: purpose, when to call, how to handle edge cases (decline), parameter details, and return value format. It is complete for effective agent use.

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 adds value by explaining the format of `decision_id` ("<date>/<symbol>") and the context for `reason` (especially when declined). While the Args section is somewhat redundant with the schema, it provides a clear, contextual listing that helps the agent understand parameter relationships.

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 explicitly states the verb 'Record' and the resource 'execution of committee verdict'. It distinguishes itself by specifying the scope (whether the user executed or declined) and mentions idempotency and retry safety, which are unique traits among siblings.

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 provides explicit when-to-call scenarios: 'when the user says "I bought it / I didn't buy / I disagree"'. It also gives specific guidance for the decline case: ask one short question for the reason first, referencing the sibling tool `decisions` and the adoption-rate loop.

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?

Despite annotations covering readOnly=false/destructive=true, the description adds substantial behavior the annotations cannot convey: no cash is touched, history is tagged `funding_source: external_funding` / `source: mcp:existing_position`, duplicate calls double-count unless retried with the same idempotency key, and the symbol is not added to the tracked list. This is consistent with idempotentHint=false rather than contradicting it.

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 purpose paragraph is well front-loaded and high value, but the trailing Args/Returns block repeats schema descriptions verbatim (units, price, currency, kind, unit_label, idempotency_key) at 100% coverage, inflating an otherwise tight definition for no new information.

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?

An output schema exists, yet the description still surfaces the error envelope; combined with the cash-neutrality guarantee, duplicate-counting hazard, gold booking convention, and alternatives, nothing material an agent needs to call this 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%, so all seven parameters (including the gold-in-CNY-per-gram rule and the idempotency_key semantics) are already documented in the schema. The Args block largely restates those same descriptions, adding little that isn't already structured, so the 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+resource (record an already-held position) with its precise niche: onboarding backfill, no ledger cash movement. It explicitly distinguishes itself from `buy` (new purchase from cash) and `track_asset` (committee coverage), so an agent can route without opening either 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?

Gives an explicit when (positions the user held before openInvest, not yet in `status`) and an explicit when-not (calling it for a symbol already in `status` adds units again — double count). It also names the two alternative tools and the conditions that select them.

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?

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds the actual failure mode ('fails if the currency's cash balance is lower than the amount'), the ledger semantics (cash debited, positions untouched, inside NAV), and the human-confirmation requirement. It slightly softens the non-idempotent annotation by describing conditional safety via idempotency_key without reconciling the two, which is a minor gap rather than a contradiction.

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 accounting distinction and the failure condition, then a compact Args/Returns block. The Args section duplicates schema text almost verbatim, which is mild waste, but the overall structure is easy to scan.

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?

Covers what matters for a destructive mutation: prerequisite confirmation, the cash-balance failure condition, what is and is not affected, and idempotent retry behavior. With an output schema present it doesn't need to explain return values, though it does so briefly anyway.

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 every parameter is already documented, including the enum for kind and the idempotency_key retry semantics. The Args block mostly restates the schema ('must be > 0', 'YYYY-MM-DD') and adds little syntax or format detail of its own, so the baseline 3 is appropriate.

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?

Names a specific verb and resource ('Record a fee or a tax the user already paid') and immediately scopes the accounting effect: 'debits ledger cash, positions unchanged. It is an account cost (inside NAV), not a withdrawal.' That explicitly separates it from withdraw and from buy/sell siblings.

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-not guidance: trade commissions need no separate entry because buy/sell already book them, and it is not a withdrawal. It also imposes a procedural rule the agent must follow — confirm amount and date with the user before calling — which is the kind of routing detail siblings can't express.

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 only generic annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description carries the real burden and does: it explains the exact ledger effect (credits cash, lowers average cost by amount/units, units unchanged), the floor-at-0 edge case, how excess is surfaced as excess_over_cost (capital gain), and the retry semantics of idempotency_key including the 'duplicate' response. This is substantive disclosure well beyond what the annotations provide.

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 behaviorally important material (mutation effect, cost floor, confirmation prompt) is front-loaded before the Args/Returns sections, which is good. The Args block duplicates the schema nearly verbatim, costing some space, but nothing is misleading and the prose is tight.

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?

Given a mutation tool with rich annotations and an existing output schema, the description supplies everything an agent needs: the precise accounting effect, the excess-over-cost special case, the required user confirmation, and idempotent-retry guidance. Nothing material is left undefined.

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% and the schema already documents each parameter thoroughly (including the detailed idempotency_key semantics). The description's Args block largely restates that information, adding only marginal framing ('must match the holding's cost currency'), so the baseline of 3 is appropriate.

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 ('Record a return of capital'), scopes it to 'some ETF / REIT distributions', and immediately distinguishes it from income events by noting it is 'a cost reduction, not income' — enough to separate it from siblings like record_dividend or record_fee without opening a 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?

It gives a clear precondition ('Confirm symbol, amount, and date with the user before calling') and the qualifying context ('some ETF / REIT distributions', 'not income'), which implies when this tool applies versus a dividend recorder. It stops short of explicitly naming an alternative tool or stating a when-not-to-use case, so it lands just below the top.

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?

Annotations already flag destructiveHint=true and idempotentHint=false; the description is consistent with both and adds real context: it rewrites units and average cost, the rejection condition, and the duplicate-return behavior when reusing an idempotency_key. Return shape is mentioned but an output schema already covers that, so it is a modest addition rather than a gap.

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 behavior and mutation warning, then the rejection rule, then a caution. The trailing Args/Returns block duplicates the JSON schema descriptions verbatim, which is redundant, but the prose paragraphs themselves are tight and every sentence carries information.

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 destructive, non-idempotent mutation with 6 parameters, the description covers the arithmetic effect, the confirmation requirement, the double-apply hazard, the rejection condition with its workaround, and retry semantics. An output schema exists, so the brief Returns line is sufficient rather than insufficient.

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 the schema already documents all six parameters, and the Args block largely restates it. What the description adds beyond the schema is the derived semantics — that units multiply by ratio while average cost divides by it, with cash untouched — which tells the agent the actual effect of the ratio value.

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 ("Record a stock split / reverse split") and immediately gives the arithmetic effect: units x ratio, average cost / ratio, cash unchanged. This clearly separates it from sibling mutation tools like record_dividend, record_return_of_capital, and record_fee.

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?

Explicitly says to call it once per split and warns that a second call multiplies the position again. It also names the precondition that causes rejection (existing trades/corrections on or after trade_date) and the escape hatch (ledger_only=true), plus a confirmation-before-calling instruction.

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?

Annotations already mark the tool as destructive (destructiveHint: true). The description adds specific behavioral context: only user-added feeds can be removed, default feeds are protected. This goes beyond the annotation's binary flag.

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 concise sentences, front-loaded with the main purpose, followed by a key limitation. No unnecessary words or redundancy.

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?

The description adequately covers the tool's function and main constraint for a simple delete operation. With an output schema present, return values are not needed. Minor gap: no mention of behavior for non-existent keys or confirmation requirements.

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% with a description for the 'key' parameter that already specifies it can be a feed name or URL and excludes defaults. The tool description adds no additional semantic value beyond what the schema provides.

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?

Description uses specific verb 'Remove' and resource 'user-added news feed', clearly distinguishing from sibling tools like add_news_source and news_sources. It also explicitly states that built-in default feeds cannot be removed.

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?

Description indicates when to use (remove user-added feeds) and when not (defaults cannot be removed). It provides clear context but does not explicitly name alternative tools for adding or listing feeds, though those are implied by sibling names.

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?

Goes well past annotations: discloses the hard dependency on a backend LLM key, the 30-90s cache-miss latency, caching semantics keyed to the day plus `force`, and streaming progress notifications per debate phase. It also adds a safety framing ('Decision support only — the human always executes') and warns that `confidence_lookup` should supersede the self-reported confidence, which the annotations say nothing about.

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 and latency/caching caveats are front-loaded in the first two paragraphs, and the Args/Returns structure is easy to scan. It is somewhat long and the Args block duplicates schema text that is already 100% covered.

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?

Covers everything an agent needs before calling: symbol formatting edge cases (bare 6-digit code rejected, FUND: prefix), auth dependency, latency, cache-busting, and the fact that the return shape differs between cached:false and cached:true including the input_health block. Even with an output schema present, the path-dependent shape difference is essential context that the schema alone would not convey.

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 every parameter is already documented; the description's Args block largely restates the symbol and force text verbatim and adds only the effective default for max_rounds. A baseline 3 is appropriate when the schema carries the full parameter burden.

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?

Names a specific verb and resource ('Run the 4-role LLM investment committee on a symbol') and spells out the roles and the output (a CIO-synthesized BUY/HOLD/SELL memo). The '(Direct path)' label hints at a staged alternative but never names prepare_committee/submit_committee, so sibling differentiation is implied rather than 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?

Gives clear operating context: a backend LLM key is required, a fresh run takes 30-90s, and today's cached verdict is returned unless `force` is set. It also steers the agent away from a sibling ('no need to call explain_decision just to read them'). What's missing is an explicit statement of when to prefer the staged/alternate committee path over this direct one.

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?

The annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantive context beyond them: which ledger fields change (units down, average cost unchanged, cash credited in cost currency), the warning that cash moves, and the retry/dedupe behavior of the idempotency key. No contradiction with the annotations — a fresh call with a new key legitimately sells more, consistent with idempotentHint=false.

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-loads the ledger effect and the pre-call confirmation, then organizes details under Args/Returns headings. Slightly redundant with the schema's parameter descriptions, but every section earns its place for a cash-moving mutation.

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 destructive, cash-affecting mutation with an output schema present, the description covers what the tool does, what it alters, the confirmation requirement, and retry semantics. Nothing an agent needs in order to call it safely is missing, and return values needn't be expanded since the output schema exists.

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 all four parameters including idempotency_key semantics are already documented in the schema. The Args block largely restates those same definitions with no added syntax, format, or edge-case guidance. Baseline 3 is correct.

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 ('Record a sell in the local ledger') and immediately describes the ledger effect: reduces units with average cost unchanged, credits cash in the holding's cost currency. It also distinguishes itself from order-placing siblings by stating openInvest never places real orders, so an agent can tell it apart from place_fund_order or record_execution.

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 pre-call guidance ('Confirm symbol, units, and price with the user before calling; this moves ledger cash') and scopes the tool to bookkeeping already-executed trades, which routes the agent away from real-order tools. It stops short of naming a specific sibling to use instead in ambiguous cases, so it is strong but not exhaustive.

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?

Annotations already declare mutation (`readOnlyHint: false`), idempotency, and non-destructiveness, but the description adds substantial behavioral context: writes are validated and atomic, invalid writes roll back, clearing semantics differ for rules vs whole symbols, and alerts are only delivered when `INVEST_EVENT_ALERT=1` is set.

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 front-loaded with purpose and usage, then organized into Args and Returns. Some Args content duplicates the already rich schema descriptions, but the structure remains clear and the extra detail is not harmful.

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?

Given a mutation tool with four optional parameters, rich annotations, an output schema, and nested alert/target maps, the description supplies the remaining operational context: atomic validation, rollback behavior, sum constraints, and alert delivery prerequisites. Nothing critical appears missing for correct invocation.

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 schema already documents each parameter thoroughly, including examples, clearing behavior, and percentage-point semantics for alerts. The description's Args section largely restates those constraints rather than adding new parameter-level meaning.

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 (update) and resource (strategy target allocation) with the exact fields affected: stock/cash ratio, per-asset target weights, and alert lines. It also names related consumers (`rebalance_plan` and the price sentinel), making the tool distinguishable from siblings.

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 concrete user-utterance examples such as 'set my target to 70% stock / 30% cash' and 'put 30% in 510300.SS and 20% in gold'. It also explains a key conditional workflow: lowering the stock target below current per-asset weights requires passing new weights in the same call. It does not provide explicit when-not-to-use guidance or name sibling alternatives for adjacent tasks.

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?

Annotations only declare readOnlyHint; the description adds the operationally important fact that it fetches live quotes so values change between calls — an agent must know not to cache or compare stale snapshots. It also discloses degradation behavior (null price fields on unavailable quotes, {"status": "insufficient_history"} until two trading days of ledger exist) and conditional field presence, none of which is inferable from the annotation.

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?

Structure is good — purpose, then when-to-use, then returns, front-loaded correctly. But the Returns block runs long for a zero-argument tool and largely re-enumerates fields the output schema already defines (fx, total_assets_cny, performance, income_30d, pending_fund_orders), burying the genuinely useful caveats (null quotes, is_tracking_only rows, insufficient_history) inside field-by-field detail.

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 high-complexity portfolio snapshot the description covers the full surface an agent needs: what is returned at a summary level, how missing quotes and tracking-only assets appear, the insufficient-history state, and that figures shift between calls. An output schema exists, so it is not required to enumerate returns — doing so makes it more than complete, not less.

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?

Zero parameters, so there is no parameter semantics to explain; the baseline for a no-arg tool applies. Nothing in the description misdescribes or implies hidden inputs.

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?

Opens with a specific verb and resource plus an enumeration of scope: cash per currency, units/avg cost/live price per holding, unrealized P&L per position and total. That is far more than a restatement of the name. It stops short of a 5 because it never names the overlapping siblings (live_prices, daily_report, history) that an agent might otherwise reach for when it just needs quotes or a summary.

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 concrete trigger phrases ("show my portfolio", "how is my P&L") and a forward-looking trigger ("before proposing any trade"), which is real routing guidance rather than implied usage. No exclusions or named alternatives, so it sits at a clear 4 rather than 5.

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?

Annotations provide readOnlyHint=true. The description adds context about the return value structure and the nightly Dreaming job, enhancing transparency beyond what annotations provide.

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?

Well-organized with clear sections and bullet points, though slightly verbose. Every sentence adds value, making it effective without being overly long.

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?

Given zero parameters and an existing output schema, the description fully covers the tool's purpose, usage, and return structure. No gaps remain.

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?

No parameters exist, so baseline 4 applies. The description does not need to add parameter information.

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 states it retrieves the user's investment strategy, including target allocation, tracked assets, and insights. This distinguishes it from sibling tools like set_allocations, track_asset, and untrack_asset.

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?

Explicitly tells when to use: 'Use when deciding whether a proposed trade fits the user's plan, or when the user asks "what is my strategy / what am I tracking".' Also marks as read-only, differentiating from mutating tools.

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?

Annotations declare readOnlyHint=false / idempotentHint=false / destructiveHint=false, and the description is consistent with the mutation claim ('saves the decision'). It adds real behavior beyond annotations: the no-parseable-verdict error path, the deterministic rules applied, and the facts_source distinction. It does not clarify whether resubmitting creates a duplicate decision, which matters given idempotentHint=false.

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 workflow step, then error handling, then returns. The Returns section restates what the output schema presumably carries, but the whole thing is compact and each section does useful work.

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?

Covers the happy path, the error path, and the facts_source semantics, which is enough for an agent to call and recover correctly. With an output schema present, the returns prose is redundant, and the repeat-submission/idempotency question is left open.

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 schema already documents symbol, transcript sections, model, and provider. The description confirms the symbol must match prepare_committee but adds no syntax or constraint detail beyond the schema. 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+resource ('hand in the transcript', 'Step 2 of the agent-run committee') and anchors itself to the workflow step, naming prepare_committee as the predecessor. An agent can distinguish it from prepare_committee and run_committee without opening schemas.

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?

Explicitly frames itself as step 2 following prepare_committee and contrasts the agent-run path with the 'backend-run committee'. It also states the failure condition and remediation. It never explicitly says when to prefer run_committee over this path, so it stops short of full alternative routing.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing alert cooldowns (24h for price lines, once per trading day for day-move lines), that each passed alert line overwrites only that line, the target-weight sum rejection condition, and the server-side INVEST_EVENT_ALERT=1 delivery gate that silently degrades to logging. This is exactly the kind of non-obvious operational context the description should carry.

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 purpose and usage sentences are front-loaded and earn their place, but the long Args section duplicates parameter descriptions already present at 100% schema coverage, adding bulk without new information for most fields.

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 12-parameter mutation with a full output schema, the description covers the mutation semantics, alert lifecycle, failure modes (weight-sum rejection), and the error return shape, leaving no significant gap an agent would need to guess at.

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% and the Args block largely restates the schema descriptions verbatim, so baseline 3 applies. A few additions are real ('3 = 3%, not a 0-1 fraction' caveat, overwrite-per-line behavior), but most parameter meaning is already in the structured 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?

Opens with a specific verb+resource ('Add a symbol to the tracked-asset list, or update an existing entry') and immediately characterizes the operation as an idempotent upsert with per-field semantics. It clearly differentiates itself from untrack_asset and set_allocations, which it names explicitly for the clearing case.

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 concrete trigger phrases ('track AAPL', 'alert me when X drops below N', 'tell me if it falls 3% in a day') plus the update cases (cap/channel/fees/target weight). It also routes the agent elsewhere for clearing a line ('use set_allocations with a null value'), so when-to-use and when-not-to-use are both covered.

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?

Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds critical context: holdings and trade history are untouched, and schema guarantees at least one tracked asset remains.

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 two short paragraphs, no redundancy, and front-loaded with the main action. Very efficient, though the Args and Returns could be integrated.

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 one parameter, good annotations, and mention of output schema, the description covers effects, safety, validation, and error handling fully.

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% with a clear description of the 'symbol' parameter. The description repeats the same info without adding new meaning, meeting the baseline.

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 specific verbs ('Remove', 'stop covering') and clearly identifies the resource ('tracked-asset list'). It distinguishes itself from the sibling 'track_asset' and other trading 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 states the action and notes a validation constraint (at least one asset remains), but does not explicitly provide when to use this tool versus alternatives or when not to use it.

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?

The annotations already declare readOnlyHint=true, and the description adds significant behavioral context: 'pure arithmetic over current holdings — no LLM call, instant, free.' It clarifies the tool has no side effects, is fast, and free, which goes well beyond the annotations. No contradiction.

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 concise and well-structured: a short intro, usage guidance, parameter explanations, and return description. It is front-loaded with the key purpose and contains no unnecessary words. Every sentence adds value.

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?

Given the tool has only 3 parameters, an output schema exists, and the description covers purpose, usage, parameters, and returns, it is fully complete. Additional details like 'instant, free' provide useful context. No gaps.

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?

With 100% schema description coverage, baseline is 3. The description adds value by reiterating the mutual exclusivity constraint 'Provide exactly one of pct or price' and clarifying the symbol parameter as 'yfinance ticker held or tracked by the user' beyond the schema's description. This earns a 4.

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 states the tool's purpose: 'Simulate portfolio P&L for a hypothetical price move' and distinguishes it from siblings by emphasizing it is a pure arithmetic simulation with no LLM call, instant, and free. This specificity and differentiation from tools like buy/sell/track earns a top score.

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 explicitly says when to use: 'when the user asks scenario questions like "if the Nasdaq drops 10%, how much do I lose"' and provides clear guidance on parameters: 'Provide exactly one of pct or price.' While it does not explicitly state when not to use, the context makes it clear for hypotheticals, so it earns a 4.

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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=false) it discloses the insufficient-balance failure mode, the bookkeeping-only scope, and dedup behavior on key reuse. The idempotency_key emphasis sits in mild tension with idempotentHint=false, though the annotation describes default no-key behavior, so it is not a contradiction.

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 opening one-line summary is well front-loaded, but the Args block duplicates fields already fully covered by the schema, and the Returns line overlaps an existing output schema. Several sentences do not earn their place, diluting an otherwise tight core.

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 destructive ledger mutation with annotations and an output schema present, the description supplies the mutation intent, failure behavior, scope caveat, and idempotency guidance an agent needs to call it correctly. Return-value explanation is redundant given the output schema, but nothing essential 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%, so the schema already documents currency, amount, and the idempotency_key dedup semantics in far more detail. The description's Args block largely restates the schema and adds no syntax or format information beyond it, so the 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?

Specific verb + resource ("Record a cash withdrawal from the ledger") makes the operation unmistakable and distinguishable in nature from deposit/buy/sell siblings. It stops short of explicitly naming any sibling or routing rule, so it is clear but not sibling-differentiating.

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 implies when it applies (recording an outflow) and states a failure condition ("Fails if the balance is insufficient") and a scope caveat ("no real payment system is connected"). However it never says when to prefer this over deposit/buy/record_fee or how to sequence it, so usage is only implied.

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