Hedgr FX Risk & Treasury

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

Annotations already establish the safe-read profile, but the description goes further by disclosing conditional response states (entity_scope.ask_user, connection_status.state='setup_required' with setup_url/setup_steps) and per-provider prerequisites (Sheets/CSV need Company & reporting completed). It adds real behavioral context, though some of it overlaps the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, but the bulk of the text is a dense enumeration of return-value nuances that an output schema already exists to carry. Sentences about provider behavior and setup states are informative but not all earning their place for an agent that will also read the output 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?

Return semantics are well covered (and reinforced by an output schema), but an agent in a 27-tool family gets no routing help against close siblings like get_workspace_setup_state or get_platform_capabilities. Adequate but with a clear selection 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?

Zero parameters, so the rubric baseline of 4 applies; the schema fully documents 'No inputs. Returns workspace connection and onboarding status.' There is nothing further for the description to disambiguate.

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 ('Returns the current state of the user's Hedgr account') and enumerates what that state covers (accounting systems, Sheets/CSV workspaces, setup sections). However, it never distinguishes itself from the very similarly scoped sibling get_workspace_setup_state, leaving an agent to guess which to call.

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 is purely declarative about return contents; it never says when to call this tool, when not to, or which sibling covers overlapping needs. The conditional states (setup_required) hint at a preflight check but stop short of an actual usage directive.

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 readOnly/no-destructive/openWorld=false, but the description adds substantial behavioral context beyond them: determinism, the P10-P90 band, named drivers, walk-forward accuracy metrics, and the sufficient_history=false signal for short histories. That is rich disclosure of output character and reliability limits.

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 scope, then qualifications; each sentence carries distinct information. It is fairly dense and long, but no sentence is redundant 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?

An output schema exists, yet the description still sketches the return shape (per-currency net, band, drivers, accuracy) and flags the sufficient_history edge case, which is exactly the extra an agent needs to interpret results. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are fully documented in the schema, including the default 8 and the 1-26 range. The description only restates the horizon in prose ('next N weeks, default 8') and never addresses the currency filter, so it adds little beyond the schema 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?

States a specific verb+resource (projects expected net cashflow per currency) and immediately scopes it to the user's own settlement history, which cleanly separates it from siblings like get_fx_exposure or get_funding_forecast. The explicit 'NOT an FX-rate prediction' clause further disambiguates.

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 context for when this applies (own settlement history, open invoices, recurring/seasonal flows) and rules out the FX-prediction use case. It does not name a specific sibling alternative to reach for instead, so it stops short of full when-not 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new behavioral context: an unscoped call additionally returns maturity_ladder, cashflow_coverage, and hedge_maturity_coverage, while a scoped call does not. That conditional-output disclosure is the kind of trait annotations cannot express. It does not cover rate limits, auth needs, or timing/latency.

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 leads in the first clause, usage follows, and the conditional-output detail is last, which is a sensible front-loaded ordering. Both sentences are dense and largely earn their place, though the middle list of bucket labels is long and edges toward enumeration for its own sake.

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-required-parameter read tool with an output schema and full annotation coverage, the description supplies everything an agent needs: scope semantics, the trigger question types, and the fact that unscoped calls return additional aggregates. Nothing material 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 baseline is 3, and both parameters are fully documented in the schema. The description earns an extra point by explaining the semantic consequence of the parameter combination: omitting both yields the whole-workspace report and unlocks the extra aggregate blocks, which the schema does not state.

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 ('Returns FX cashflow timing by currency and bucket') and immediately decomposes it into receivables, payables, bank cash, and hedge maturities. This granularity lets an agent distinguish it from near neighbours like get_cashflow_forecast, get_cash_position, and get_fx_exposure 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?

The description gives explicit triggering conditions ('Monitor > Exposure & Cash Flow questions about overdue, next 30, 31-60, 61-90, beyond 90, undated, liquidity timing, or same-currency cash coverage'), which is unusually concrete. It stops short of naming when NOT to use it or pointing to a specific alternative sibling, so it falls just 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 establish readOnly, non-destructive, closed-world behavior, so the description is free to add analytical context instead of repeating safety. It does so meaningfully by disclosing the interpretation of the result: whether FX cash offsets invoice exposure in the same currency. It still omits freshness/refresh behavior of the balances, which keeps 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?

Two sentences, front-loaded with the core capability, and the second sentence earns its place by explaining the analytical value of the result rather than padding. No redundant restatement of the name or 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. Purpose and interpretation are well covered; the remaining gap is routing guidance versus related reads such as get_fx_exposure or get_cashflow_forecast.

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 three parameters (currency, entity_id, include_chart) are already documented with pattern, default, and chart rendering detail. The description adds only a loose 'by currency and entity' restatement and no new parameter semantics, 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 and resource ('Returns current cash balances') plus the dimensions of the result (by currency and entity). It is distinguishable from forecast siblings like get_cashflow_forecast by the word 'current', but it does not explicitly name a sibling or draw the boundary against get_fx_exposure.

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 gives no when-to-use guidance, no prerequisites, and no named alternatives. The only usage hint ('Omit for group-level consolidated cash position') lives in the entity_id schema field, not the description, so the prose itself carries no routing information.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered; the description's 'compact read-only snapshot' is redundant with that. The genuinely additive behavioral disclosure is the entity_scope.ask_user interactive behavior when several entities are consolidated, but this arrives after a long enumeration of return fields that the output schema already covers, so the net new behavioral content is thin.

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 trigger are front-loaded in the first sentence, which is good, but the description then runs long enumerating return blocks (book_value, invoice_book, profit_and_revenue, data_coverage, etc.) that an output schema already documents. Much of that length does not earn its place and dilutes the key behavioral point about entity_scope.

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?

Because an output schema exists, the description need not re-explain return values, yet it spends most of its length doing so. The interactive entity_scope behavior is covered, but the description leaves the agent without routing guidance against the many overlapping dashboard-slice siblings, so completeness for correct invocation is only adequate.

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 single entity_id parameter is already fully documented in the schema (including the consolidated-group default and aligned_blocks_scope_basis). The description adds no syntax, format or default detail beyond what the schema provides, 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: 'Returns a compact read-only snapshot of the authenticated Hedgr dashboard,' and enumerates the scope (organisation, provider, base currency, entity context, exposure, P&L). It is clear what the tool does, though it never explicitly names the sibling slice tools (get_pnl_attribution, get_fx_exposure, get_cash_position) it aggregates over, so differentiation is left implicit.

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 one trigger condition, 'Use when the user asks for a dashboard-level summary,' which is more than nothing but gives no when-not guidance and names no alternatives, despite 26 heavily overlapping siblings. The agent must infer that this is the roll-up view versus the per-slice 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 cover the safety profile (readOnly, non-destructive, closed-world). The description adds a genuine behavioral detail not in the annotations: an unscoped call returns additional sections (decision_readiness, balance_validation, scout_currency_quality, data_coverage) that a scoped call does not, so the shape of the response depends on how it is called.

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 use case, then a return inventory. The middle sentence is a long comma-separated list that is dense, but each item is informative and no sentence is filler.

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 enumerating return values is partly redundant, yet the description covers scoping behavior, use cases, and safety context for a 2-param read tool. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining that omitting scope filters changes the returned payload ('On an unscoped call also returns...'), which gives the optional parameters semantic weight rather than just being filters.

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 ('Returns') plus the resource ('safe import and data-quality diagnostics') and then enumerates the concrete signals returned (duplicate invoice IDs, missing fields, rate gaps, P&L readiness). This is far more specific than the sibling get_* tools and lets an agent distinguish it 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?

Explicitly names the triggering questions: 'why CSV imports failed' and 'why P&L is incomplete'. That is clear context for use, but it offers no exclusions or named alternatives (e.g. get_account_status) for adjacent questions.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is low, but the description adds genuinely new behavioral limits: it does not download files, does not expose temporary URLs, and does not create private report drafts through MCP. That tells an agent precisely where the tool's authority ends.

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, zero filler, with the positive statement of purpose front-loaded and the boundary conditions following. Every clause carries information an agent would otherwise have to guess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return values, and with zero parameters there is no input to document. What remains — what the tool produces and what it explicitly will not do — is fully covered.

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 and the schema states 'No inputs', so there are no parameter semantics to clarify. The description correctly adds no parameter noise, which is the right behavior for a no-arg tool.

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 ('Returns a read-only manifest of Hedgr exports') plus the scope ('available in the dashboard and where to generate them'). It is clear what the tool yields, though it never names or differentiates itself from any sibling beyond the implicit read-only family pattern.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the negative boundary ('Does not download files, expose temporary URLs, or generate private report drafts through MCP'), which tells the agent this is a discovery step rather than a retrieval step. However, it never states when to call it versus other discovery tools such as get_dashboard_context or get_platform_capabilities, and no alternative is named.

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 readOnly/destructive annotations: it discloses the data provenance (real bank balances + real invoices plus a projected settlement component with band and accuracy), that trade direction is a mechanical consequence of the gap sign rather than a recommendation, and the meaning of sufficient_history=false. This is exactly the behavioral context annotations cannot 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?

Front-loaded with the core identity before listing capabilities, and nearly every clause carries distinct information. It is a dense single paragraph, though, and the middle run-on enumerating answers slightly taxes readability.

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 explained, yet the description still names key output concepts (can_self_fund, base_funding_shortfall, sufficient_history) and the data sources. For a 2-param, read-only forecast tool, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both currency and horizon_weeks (including the 1-26 range and default). The description reinforces the per-currency/base-currency framing but adds no syntax or format detail beyond the schema, 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 and resource (a per-currency running cash-balance funding forecast) and explicitly scopes it against siblings by noting it INCLUDES base currency 'which the FX-exposure tools deliberately exclude'. An agent can distinguish it from get_fx_exposure 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?

Clearly frames the questions it answers (will the user hold units to settle payables/receivables, first date each currency runs short) and routes away from FX-exposure tools. However, it does not explicitly contrast with other nearby siblings like get_cashflow_forecast or get_cash_position, so the when-to-use is clear but not fully disambiguated.

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 the read-only/safe profile, and the description goes well beyond that: bucket definitions, undated-invoice handling, confirmed-vs-forecasted distinction, provenance in a source field, inter-company mode honoring, the caveat that realised P&L does not move with that mode, and the additional blocks returned on an unscoped call. This is rich behavioral context an agent could not get from the structured fields.

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 and bucketing scheme are front-loaded, and each sentence carries genuine behavioral content rather than filler. The remaining text is extremely dense and packs multiple concepts per sentence, which slightly hurts scannability but does not waste 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?

For a read-only analytical tool with a full schema and an output schema, the description is more than complete: it explains what the payload contains, how scoping changes the result, and edge-case semantics (undated buckets, inter-company mode). An agent has everything needed to call and interpret it.

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 five parameters with formats and defaults. The description adds only indirect meaning via the scoping discussion ('unscoped call', currency/entity filtering implied), 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?

States a specific verb and resource ('Returns net FX exposure') and enumerates the dimensions of the result (currency pair, entity, time bucket). It is clearly distinguishable from siblings like get_fx_guidance or get_hedge_portfolio, which cover guidance and hedging rather than raw exposure.

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 usage through conditional behavior ('On an unscoped call also returns counterparty_concentration...'), effectively telling the agent that omitting filters yields a broader payload. However, it never explicitly states when to choose this tool over siblings such as get_fx_guidance or get_hedge_portfolio, leaving routing 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context - that only a public-safe subset is returned and internal partner/marketing guidance is filtered out - which is useful, but it omits return format, currency/scope limits, or any rate considerations.

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, front-loaded with the primary return value before the filtering caveat and the disclaimer. Efficient overall, though the trailing advice disclaimer is marginal to tool selection.

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?

Because an output schema exists, the description needn't explain return values, and with no parameters and clear annotations the burden is light. It adequately covers what the tool is and how the returned set is scoped; only alternative-routing guidance 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 no parameters. With zero inputs and 100% schema coverage, there is nothing for the description to clarify, so the baseline of 4 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 ('Returns Hedgr's shared FX-guidance canon') and clarifies it is read-only methodology. The FX-specific framing separates it from generic siblings like get_policy, though it never explicitly names a sibling it is distinct from.

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 explains what the tool returns but gives no when-to-use or when-not-to-use guidance, and never references alternatives such as get_policy or get_rate_assumptions. An agent must infer the invocation context purely from content description.

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 readOnly, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious behavioral semantics: hedges are drawdown-normalised, parent forwards are listed once at remaining notional, and child draws are excluded to match the dashboard hedge book — details an agent could not infer from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the sentences earn their place by explaining the drawdown-normalisation rule. The trailing enumeration of return fields (coverage, policy_band, residual_coverage, drawdowns, hedge_mark_to_market) is somewhat redundant given an output schema exists, which keeps it from a 5.

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 read-only portfolio tool with a full schema and an output schema, the definition covers the data semantics an agent needs (normalisation, dashboard alignment, permission-free access) without over-explaining return values. Minor gaps like pagination or portfolio size limits remain unaddressed.

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 three parameters are already documented in the schema. The description only gestures at filtering via the 'hedge ratio on EUR' example and adds no format, default, or syntax detail beyond the schema, warranting the baseline 3.

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 (returns) and resource (open forward contracts and hedges) and enumerates the key fields returned (maturity, notional, contracted rate, mark-to-market). This clearly distinguishes it from siblings such as get_fx_exposure or get_protection_builder_snapshot, which address exposure or candidate trades rather than the live hedge book.

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 a concrete usage scenario ('what is my current hedge ratio on EUR?') and clarifies it works without execute permissions, which helps an agent choose it over an execution-oriented tool. It stops short of naming a specific alternative sibling or stating 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond that: the four return categories and the specific 80% 'approaching' threshold, which the annotations do not 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?

Front-loaded with the core comparison, then status definitions and use cases in a compact form. The closing sentence ('Limits are set in Control > Comfort Limits') partially restates the opening 'Control tab' reference, minor 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?

For a read-only, single-optional-param tool with an output schema, the definition covers purpose, statuses, and use cases adequately. The only gap is lack of explicit sibling routing, which is minor given the distinct concept.

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% with a single optional entity_id whose omission semantics are already documented in the schema. The description adds no further parameter syntax or format detail, 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 and resource ('Compares current net FX exposure against per-currency comfort limits') and clarifies scope. It is clearly distinguishable from sibling get_fx_exposure by adding the limit-comparison dimension.

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 gives concrete use cases via quoted questions ('are we within limits?', 'which currencies need attention?'), which grounds the when-to-use. However, it does not explicitly name alternative sibling tools (e.g., get_fx_exposure) or state 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds real behavioural context beyond that: regimes are explicitly 'not trade recommendations', scores are 'analytical only', and dashboard_market_environment returns 'null with a reason until the Monitor tab has published' — a genuine data-availability caveat 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?

The purpose is front-loaded, but the body is a sprawling run-on list that enumerates return fields (headline, rows, rate, regime, 30-day change, methodology, dashboard surface, composite/volatility/trend scores) at length — content that an existing output schema already carries. Substantial redundancy dilutes the 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?

An output schema exists, so return-value enumeration was not required; the description is nonetheless complete for a read-only analytical tool with sensible null-state disclosure. Its gaps are the missing sibling routing and the return-field bloat rather than any missing operational fact.

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 pairs, history_years, include_chart and include_history including defaults and bounds. The description adds little parameter-level meaning (only the loose 'one or more currency pairs' and the exposure-conditional behaviour), so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope ('Returns a current Hedgr regime snapshot for one or more currency pairs') and names the volatility regime taxonomy. It does not, however, draw a clear line against similarly-flavoured siblings such as get_fx_guidance or get_dashboard_context, so an agent must infer the boundary.

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 single cue 'Use for market-backdrop questions' gives an implied usage context but names no alternatives and no when-not conditions, even though the sibling list contains several plausible substitutes (get_fx_guidance, get_fx_exposure, get_dashboard_context). Minimum viable, not directive.

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, destructiveHint=false and closed-world, so safety is covered. The description adds real context beyond that: it discloses the exclusion set (admin routes, operator pages, feature-flag internals) and that labels are 'current', signaling state-dependent output.

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, each doing distinct work: what it returns, when to use it, what it excludes. Purpose is front-loaded and there is no filler.

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-shape explanation is not required. For a zero-parameter read tool, the description covers purpose, trigger, and scope boundaries fully; an agent needs nothing else to select and call it.

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 no parameters, so the baseline is 4. The schema and description both confirm 'no inputs', and there is nothing further a parameter discussion could add.

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 ('Returns ... Hedgr navigation targets') plus the exact payload (current tab/subtab labels and what each surface is used for). This is clearly distinguishable from every sibling, all of which return financial or account data rather than UI navigation metadata.

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 trigger condition: use for 'where do I find this in Hedgr' questions. It also bounds scope by exclusion (admin routes, operator pages, feature-flag internals). It does not name an alternative tool, but no sibling competes for this intent, so the guidance is sufficient.

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 the safe-read profile; the description goes well beyond by disclosing that due-date rates may be unavailable, that undated invoices are excluded from driver rows and surfaced separately via undated_invoice_count / undated_base_amount / undated_by_currency, and how P&L is split. These are non-obvious behavioral traits an agent cannot get from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, all carrying distinct information (scope, ordering, P&L split, undated handling, use cases), with the primary purpose front-loaded. The undated-invoice sentence is dense but earns its place by preventing a common misinterpretation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return values, and it still covers scope defaults, edge cases, and intended use cases. Nothing an agent needs to invoke or interpret this read-only report 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% and both optional parameters are already fully documented (currency ISO pattern, entity_id from list_entities, omit-for-workspace semantics). The description adds the 'by currency' framing but no additional parameter syntax or defaulting nuance, 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?

The description names a specific verb and resource ('Returns overdue invoice drivers by currency and top contact'), states the ordering logic ('prioritised by largest exposure per currency'), and describes the exact output decomposition (unrealised FX P&L vs since-due P&L). An agent can distinguish this from the many other cashflow/exposure siblings 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 concrete triggering questions: 'what is driving overdue invoices?' and 'what did overdue invoices cost us?', which clearly frames the intended use. There are no explicit exclusions or named alternative tools, so it falls 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 cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context: results may be detected patterns 'where available' or derived from settled invoice dates, and output is timing-only with no gain/loss figures. It doesn't state coverage limits or caveats on the derived fallback, but the added context is substantive.

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, each earning its place: what it returns, when to use it, and what it deliberately excludes. The most important scoping detail (timing-only, derived fallback) is front-loaded with zero filler.

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-value documentation is not required, and the description covers the fallback data source and the timing-only scope. Given a low-complexity read tool with fully documented optional params, this is nearly complete; only the boundary against sibling timing/driver tools is 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% with both optional filters fully documented (ISO 4217 pattern, entity_id from list_entities, omit-for-all semantics). The description's 'by counterparty and currency' maps to the params but adds no syntax or format detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Returns detected payment timing patterns') and resource, with the two dimensions that scope it (counterparty, currency) and a data-source fallback. It does not explicitly distinguish itself from near siblings like get_cashflow_timing or get_overdue_drivers, so an agent must infer the boundary.

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?

'Use for factual questions about who pays late or early' gives a clear trigger context, and 'Reports timing only, not realised gains or losses' sets a boundary on what questions it answers. No alternative tool is named for the adjacent cases, so routing still requires 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?

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description goes further by disclosing the negative boundary — private prompts, formulas, credentials, admin pages, source paths, internal routes, feature flags and implementation IP are deliberately withheld — which is behavioral context the schema cannot express.

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 payload enumeration is front-loaded in the first sentence and the usage condition follows immediately. The list-heavy construction is dense but each item earns its place by delimiting scope; it runs slightly long but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no inputs, an output schema present, and annotations covering the safety profile, the description supplies everything else an agent needs: what it returns, when to reach for it, and what it deliberately omits. Nothing required 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, which is the baseline-4 case; the schema is empty and self-describing, so there is nothing for the description to compensate for. It adds no param detail, but none is 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?

Specific verb (returns) plus a precise resource (a safe, client-facing capability map) with an enumerated payload: dashboard tabs, data sources, MCP surfaces, coverage summary, and the Scout/MCP boundary. It is clearly distinguishable from the data-bearing get_* siblings, which return numbers rather than a description of capability.

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?

Explicit trigger: 'Use this when the user asks what Hedgr, Scout, or the connector can do.' That is a clear routing condition into a challengeable sibling set. It lacks an explicit when-not or a named alternative (e.g., get_navigation_targets vs this), 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: all amounts are in base currency, results are sorted by absolute total P&L, and the response carries Scout-aligned blocks that match what the in-app assistant quotes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentences are front-loaded and efficient, but the final sentence is a dense run-on enumerating many output keys (dashboard_hero, totals.*, contributor families, materiality, fy_windows, provider_fx_ledger). Since an output schema exists, much of that enumeration restates structured data and bloats the definition.

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 4-param, read-only reporting tool with full schema coverage and an output schema, the definition gives enough to call it correctly, including currency basis and sort order. The return-value enumeration is somewhat redundant given the output schema, but nothing an agent needs to invoke it 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 entity_id, include_chart, include_realised and include_unrealised are already fully documented in the schema. The description adds no parameter syntax or format detail beyond that, 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 ('Returns FX P&L broken down by currency') and enumerates the distinct breakdowns it exposes: top contributor, unrealised MTM on open invoices, and realised gain/loss from settled invoices. This clearly separates it from exposure/guidance/hedge siblings without their schemas being opened.

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 trigger questions ('which currencies are hurting us?', 'what is our total FX impact this period?', 'show me P&L by currency') that map cleanly onto when to reach for this tool. It stops short of naming an alternative tool or stating when NOT to use it, so it is strong context rather than a full routing rule.

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 the read-only, closed-world, non-destructive safety profile, yet the description goes well beyond that: it discloses that target_hedge_ratio_pct is 0 when unset, that comfort-limit rows with limit 0 are treated as unset and labelled so, and that max_single_trade_base and approval_threshold_base are returned as null with a stated reason. These sentinel-value semantics are exactly the non-obvious behaviour an agent needs to avoid misreading the payload.

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 is front-loaded in the opening clause, which is good, but the remainder is a single dense sentence enumerating stored fields and sentinel rules — much of which restates what the output schema already carries. It is informative rather than padded, but not efficiently portioned.

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?

Since an output schema exists and annotations cover safety, the description need not explain return structure at all; it nonetheless supplies the sentinel semantics that give those returns meaning. The one real gap is the absence of routing guidance against the neighbouring policy/guidance tools.

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?

Only one parameter exists and the schema documents it fully (the entity_id description already explains the omit-for-group-level behaviour), so coverage is 100%. The tool description adds nothing to entity_id, but with the schema doing the work 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 first clause states a specific verb and resource — 'Returns the user's saved FX policy in declared form' — which is unambiguous and distinguishable from most siblings like get_fx_exposure or get_hedge_portfolio. It does not, however, explicitly differentiate itself from the closer siblings get_fx_guidance or get_policy_backtest_summary, which an agent might reasonably confuse.

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?

There is no statement of when to reach for this tool versus alternatives (get_fx_guidance, get_rate_assumptions), nor any precondition or exclusion. The only routing-like instruction, 'Omit for the group-level policy,' is scoping of the entity_id parameter, not usage 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 and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the 'when available' conditionality (results may be absent) and the scope limitation that it is not predictive, neither of which appears in the 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 the return value front-loaded, followed by scope constraints. It is tight overall, but the third sentence partially restates the 'historical policy replay only' limitation, a minor redundancy that keeps it just below 5.

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-input getter with an output schema, the description covers what is returned and the key usage constraint so an agent can call it correctly. It does not address what the response looks like when the summary is unavailable, a small gap against full completeness.

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 per the rubric the baseline is 4. The schema's own description confirms 'No inputs,' and there is no parameter surface for the description to explain further.

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: it 'Returns a saved Control > Backtest policy replay summary... plus the policy snapshot used for context.' That is clear and distinguishable from generic siblings like get_policy, though it does not explicitly name or contrast with an alternative sibling, which keeps it at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit positive scope ('Use for historical policy replay questions only') and a negative scope ('Does not predict future performance or recommend policy settings'). That is clear when/when-not guidance, but it stops short of naming the alternative tool an agent should reach for instead, so it falls 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond annotations by explicitly enumerating what the tool does NOT do (no trade execution, no broker instructions, no quote IDs, no hedge recommendations), which prevents the agent from misusing it as an action tool. It does not mention rate limits or caching, but the explicit negative capabilities are meaningful.

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 efficient sentences: the first defines what is returned, the second lists exclusions. No redundancy, front-loaded with the core purpose. Every 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?

Given a read-only tool with an output schema, one well-described optional parameter, and clear annotations, the description is nearly complete. It explains what is returned and what is not returned. Minor gap: does not mention how to interpret the snapshot relative to sibling forecast/exposure tools, but the output schema presumably handles the return structure. Good enough 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?

With only one optional parameter and 100% schema description coverage, the schema already fully documents the currency filter (pattern, format, omitting behavior). The description adds no parameter details beyond what the schema provides. Baseline of 3 is appropriate when schema coverage is high and the description does not compensate with additional 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 (Returns) and resource (read-only Protection Builder / Scenario Builder snapshot) and enumerates the four contents it delivers (simulated row inputs, residual exposure, cashflow-aware grouping, policy sizing context). Distinguishes itself from siblings like simulate_scenario and get_protection_candidates by emphasizing read-only snapshot content.

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 delimits what the tool is NOT for (does not execute trades, produce broker instructions, return quote IDs, or recommend a hedge), which implicitly routes agents to simulate_scenario for execution-oriented needs. However, it does not name the sibling alternative explicitly or state when to use this tool vs. simulate_scenario or get_protection_candidates.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description reinforces this with 'does not execute trades, open dealing pages, or transfer assets' and adds that output is policy-derived, but it says nothing about latency, caching, or how policy_override interacts with stored policy beyond the schema text.

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, no filler, with the core identity of the tool front-loaded before the safety caveat. Slightly terse given the tool's calculation complexity, 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?

An output schema exists, so return values need not be explained, and all three parameters are fully documented in the schema. What is missing is placement in the workflow – when an agent should call this versus get_fx_exposure, get_hedge_portfolio, or get_protection_builder_snapshot – which matters for a tool with a nested override object and no required parameters.

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%, including nested policy_override fields with ranges and semantics, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already 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?

The description names a specific resource ('policy-derived candidate rows') and its content ('suggested notional amounts for open currency exposures'), so an agent knows this returns hedging suggestions rather than raw exposure data. It does not, however, differentiate itself from near-neighbors like get_fx_exposure, get_hedge_portfolio, or get_protection_builder_snapshot.

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?

There is no when-to-use guidance and no named alternative. The only routing signal is the negative 'does not execute trades, open dealing pages, or transfer assets', which tells the agent what the tool is not rather than when to prefer it over sibling exposure/hedging 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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine behavioral detail beyond that: it discloses that forward_rates_basis can be empty 'with the reason stated when no feed supplies a forward curve', and that it reports missing spot rates and placeholder booking rates, which tells the agent how to interpret edge-case output.

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, front-loaded with the resource and its payload, then the usage trigger, then supplementary fields. The middle sentence is long and list-heavy, but every clause carries concrete content rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return values, yet it still orients the agent on the most consequential edge cases (missing rates, empty forward basis, unsupported currencies). For a parameterless read tool of this breadth, nothing an agent needs to invoke or interpret it 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 there is nothing for the description to disambiguate; the baseline of 4 applies. The schema also confirms 'No inputs', reinforcing that no argument semantics 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?

The description names a specific resource (rate assumptions) and enumerates its contents concretely: spot rates, source labels, timestamps, override presence, missing rates, invoice rows, market convention, forward rates with basis, and unsupported currencies. This is clearly distinguishable from siblings like get_data_quality or get_market_regime 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?

It gives an explicit usage trigger: 'Use when users ask where a number came from or why a rate/P&L is unavailable.' That is a clear context, but it names no alternative tool for adjacent questions (e.g. general data quality), so it stops short of full when-not/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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description goes beyond them by specifying what is deliberately excluded (raw provider payloads, hidden reconciliation notes, credentials, private calculation internals) and by disclosing the 80-row cap plus invoice_rows_total, which are genuine behavioral traits 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?

Content is front-loaded into a dense two-sentence block where the primary payload is stated first and the privacy/exclusion details follow. Slightly long and partly restates the read-only annotation, but each clause carries usable 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?

Covers scope filters, the privacy boundaries, and the invoice_rows cap/total for a zero-required-parameter read tool; an output schema exists so return-value detail is not required. Gaps are minor — no freshness/timing or pagination note for the non-invoice sections.

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 both parameters are documented with their ISO 4217 pattern, example values, and 'omit for all/whole workspace' semantics. The description adds no formatting, syntax, or interaction detail beyond that, 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 and resource (transaction-log summary) and enumerates exactly what it contains: open-invoice unrealised FX rows, settled-invoice realised FX rows, bank/cash rows, counts, provenance, plus the invoice_rows table. Tied to a named UI surface (Explain > Detailed Transaction Logs), so an agent can distinguish it from siblings like get_fx_exposure or get_cash_position 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?

Usage is implied by the 'Explain > Detailed Transaction Logs' framing and the mention that the in-app Scout assistant reads invoice_rows, but there is no explicit when-to-use/when-not or named alternative to route against. Adequate but leaves selection 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?

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds domain-specific behavioral context: accounting providers supply company settings automatically, while Google Sheets and CSV/manual workspaces may require Company & reporting to be completed. This enriches understanding beyond 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 description is three sentences: the first front-loads the purpose, the second explains a specific output, and the third clarifies the distinction between workspace types. It is appropriately sized and has no obvious filler, though the repetition of 'Company & reporting' could be tightened slightly.

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 annotations covering safety, the description does not need to detail return values. It covers the purpose and the key logical distinction between workspace types. It could be more complete by explicitly stating that the tool returns onboarding completeness, but the schema description already supplies that.

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 has zero parameters, so the baseline is 4 according to the scoring rules. The schema description already states 'No inputs,' and the description adds no parameter information, which 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: 'Returns setup state for accounting, Google Sheets, and CSV/manual workspaces.' This is clear and distinct from the financial-focused sibling tools, but it does not explicitly name or contrast with any sibling to fully earn a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by explaining what the tool returns and the condition around Company & reporting, but it gives no explicit guidance on when to call it versus alternatives. The context is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's remaining detail describes the return payload (entity_scope question and entity_ids), which is largely already conveyed by the output schema, so it adds limited behavioral value beyond structured data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences that are front-loaded with the purpose, then usage, then return shape. The concrete entity example earns its place; there is little waste, though the return-shape sentence overlaps with the output 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?

With annotations, a fully documented single parameter, and an output schema, the definition covers what an agent needs to select and call it. The usage context is present; nothing critical is missing, though it could note how disconnected entities relate to the default call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single include_disconnected parameter, so the baseline is 3. The description never mentions the parameter or its default, adding nothing 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 (Lists) plus resource (connected legal entities) and further specifies the payload (base currencies and source accounting systems). It clearly contrasts with the consolidated/group perspective, so an agent can distinguish it from the get_* point-fetch 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 an explicit when-to-use condition (entity-level rather than consolidated group figures) with a concrete example (multi-entity clients). It does not name an alternative tool or state when not to use it, 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 readOnlyHint=true, non-destructive, closed-world, so the safety profile is covered. The description adds value beyond that: worst-case is a realised historical downside, not a forecast or recommendation; cross-currency pairs are shocked base-neutrally; simultaneous entries represent a correlated move; and partial coverage is surfaced in worst_case.coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose in the first sentence, then mode mechanics, caveats, and the edge case. It is dense but every sentence carries distinct information, and the caveat ('not a forecast or a recommendation') is placed where it matters rather than buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex multi-mode simulation tool, the description covers mode selection, semantics of the worst-case path, and the cross-currency edge case, and an output schema exists so return values need not be enumerated. Nothing an agent needs in order 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 description coverage is 100%, so the baseline is 3 and the schema already documents shock_bps sign convention and worst_case semantics. The description still adds meaning the schema omits, notably the base-neutral treatment of cross-currency pairs and the correlated-move interpretation of multiple scenario entries.

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: 'Models the P&L impact of exchange rate moves on the user's current net exposure (invoices + cash) and existing hedges.' It also names the two operating modes and the exact scope of each, so an agent can distinguish this simulation tool from the surrounding get_* read tools 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?

Explicitly lays out two modes with the condition that selects each: supply `scenarios` for a linear what-if, or set `worst_case: true` (scenarios then optional) for the historical adverse revaluation. It anchors worst_case to the Monitor dashboard KPI and provides a concrete worked example ('GBP/EUR moves 3% before Q3 close'), leaving little to inference.

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