ACI Risk Indicators

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

Annotations already mark this as a safe, non-destructive read, and the description adds substantial behavior beyond them: an access-tier gate (Professional and above), an interactive sign-in side effect when the user isn't authenticated, and the important caveat that the composite is an analytical aggregate rather than an ACI Risk Indicator. It also discloses that custody/regulatory/stress fields are null for mixed-module portfolios, which materially shapes how the agent should interpret results.

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?

Five tight sentences with no filler: purpose and input bounds first, then return contents, then the analytical caveat, then access/auth. Every sentence carries information an agent needs, and nothing is repeated from the schema or annotations.

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

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

There is no output schema, so the description responsibly enumerates the return contents and warns about null module-specific fields. Combined with access requirements, the sign-in side effect, and the scope of the composite, an agent has everything needed to call and correctly interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds interpretation the schema lacks: that the weight is a capital weighting driving the composite, and the aggregate size window of 2–20 positions. The constraint of ~1.0 normalization is echoed from the schema, so the added value is real but modest.

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 ("Assess the composite risk of an allocation of 2–20 providers") and immediately scopes it to a portfolio rather than a single provider, which cleanly distinguishes it from siblings like get_risk_score and compare_providers. It also names the concrete outputs (composite_score, per-provider breakdown, concentration) so the agent knows exactly what this tool produces.

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 clear preconditions for use: an allocation of 2–20 providers with weights summing to ~1.0, Professional plan access, and a sign-in flow if unauthenticated. It does not explicitly contrast this tool with alternatives such as get_risk_score or compare_providers, so the agent must infer the routing, but the context is otherwise unambiguous.

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 a safe read operation (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely useful context beyond them: the Professional-plan requirement and the fact that calling it while signed out initiates a sign-in flow, which materially affects agent behavior.

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 short sentences, front-loaded with the core purpose and return value, followed by access and auth constraints. Every sentence carries information; 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 one parameter, full schema coverage, and no output schema, the description compensates by summarizing what comes back (full details plus a comparison matrix) and covering access/auth prerequisites. 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 description coverage is 100% and the single 'slugs' parameter is fully documented with minItems/maxItems. The description's '2–5 providers' merely restates the schema bounds, adding no new syntax or format meaning, 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 (compare) and resource (providers), plus the exact cardinality (2–5 side by side) and the output shape (full details plus a per-criterion comparison matrix). This implicitly and cleanly distinguishes it from the single-provider get_provider_detail sibling.

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 'compare 2–5 providers side by side' framing makes the use case clear, and the plan gating (Professional and above) tells the agent when the tool is callable. It does not explicitly name an alternative such as get_provider_detail for single-provider needs, so it stops short of the top score.

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 readOnlyHint/openWorldHint=false annotations, the description discloses two non-obvious behaviors: a plan-gated entitlement and that calling while signed out triggers a sign-in flow. That is real context the annotations cannot convey, though error and pagination behavior remain unstated.

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 action and payload contents, followed by entitlement and auth behavior in short, additive sentences. Slightly dense enumerations but no wasted clauses.

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

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

With no output schema, the description carries the return-value burden and does so by naming the returned fields. Combined with entitlement and auth notes, it is sufficient, with only error handling left implicit.

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?

One parameter with 100% schema coverage, so the schema already documents provider_slug as slug or UUID. The description only reinforces the 'one provider' scoping, adding no syntax or format detail 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 ('Get the full breakdown of one provider's current ACI Risk Indicator') and enumerates the exact contents returned: per-criterion values, weights, weighted contributions, confidence, hard caps, stress classification. This implicitly separates it from get_risk_score, but no sibling is named explicitly.

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

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

Usage is implied by the scope ('one provider', 'full breakdown') and the access prerequisite is stated (Professional plan and above), but it never says when to choose this over get_risk_score or compare_providers.

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 cover the safe-read profile; the description goes well beyond by disclosing the score_status contract (PUBLISHED vs WITHHELD, RETIRED, AWAITING_CERTIFICATION, NOT_ASSESSED), that non-published states carry score_status_message and no value or band, the not-found behavior for unknown providers, the plan gate, and the sign-in side effect.

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, then the status contract, then access/auth caveats in descending priority. The status enumeration is long but each state is load-bearing since there is no output schema; 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?

With no output schema, the description carries the return-value burden and does so: it names the key field, its enum-like values, and what accompanies each. Auth/plan requirements and failure modes are also covered, so an agent has everything needed to call and interpret this.

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 both provider_name and provider_slug are already documented as display name and slug/UUID. The description's 'by slug or name' restates this without adding format or precedence guidance (e.g. which key wins if both are supplied, or whether name is ambiguous).

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 (get the current ACI Risk Indicator) scoped to exactly one provider, and notes the two lookup keys (slug or name). That single-provider scope is precisely what distinguishes it from siblings like compare_providers and assess_portfolio_risk.

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 operational context: Professional plan and above, sign-in is triggered if the user is not signed in, and an unknown provider returns not-found. It implies the single-provider use case versus comparison siblings, but it never names an alternative tool or states a when-not-to-use condition.

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

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: results are tier-dependent, with signed-out or sub-Professional callers receiving only code/name/description and no provider or criteria counts. It does not mention ordering, pagination, or result size, which keeps it out of the top band.

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 payload description and then the access/tier caveat. The second sentence restates part of the first ('code, name and description only') to draw the contrast with full results, which is a minor repetition but it earns its place by clarifying the downgrade behavior.

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 parameters and no output schema, the description carries the full burden of describing returns, and it does so well — field list, tier-dependent variation, and auth requirements are all covered. Only minor omissions remain (ordering, whether counts are always integers, total module count).

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 document and the baseline is 4. The description cannot add parameter meaning beyond the empty 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 ('List ACI Risk Indicator modules') and enumerates the return fields (code, name, description). The resource is clearly distinct from siblings like get_provider_detail or search_providers, but the description never explicitly contrasts itself with them, so it stops short of the top band.

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

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

Usage is only implied — an agent reading it understands this is the catalog listing for modules, and the 'no sign-in needed' note signals it can be called unauthenticated. There is no explicit statement of when to use this versus alternatives, nor any exclusions.

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

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

Annotations already declare a safe read operation, but the description adds material context beyond them: a sign-in is triggered for unauthenticated callers, Professional plan access is required, ISIN/CUSIP positions are refused outright, and matching is exact with no guessing. These are exactly the operational traits the annotations do not cover.

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 identifier rules are front-loaded, then outcomes, then access/auth, which is a sensible order. It is dense and long, but nearly every clause carries distinct information about outcomes or constraints rather than 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?

With no output schema, the description carries the return-value burden and does so by enumerating all five outcomes (resolved, ambiguous, withheld, uncovered, out_of_scope), the fields on a resolved result, and the reason_code on the rest. Access and auth requirements round out what an agent needs 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 the baseline is 3, but the description adds real meaning: it enumerates the accepted identifier kinds, explains that module_hint narrows an ambiguous outcome to a candidate module, and clarifies position_ref is echoed but never used to resolve. This goes beyond restating 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?

The description opens with a specific verb and resource: map positions to ACI Risk Indicators of the providers behind them, and it fixes the scope at up to 200. That is clearly distinct from sibling tasks like get_risk_score or assess_portfolio_risk, so an agent can select it without opening the schema.

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

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

It gives strong in-scope conditions (positions carry identifiers only, market values not accepted) and states the plan requirement, which effectively implies usage context. However, it never names an alternative sibling or explains when to prefer this bulk mapper over get_risk_score or assess_portfolio_risk, 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 readOnly/non-destructive, but the description goes well beyond them: it discloses that no sign-in is required, that signed-out or below-Professional callers receive a degraded payload (`name` and `module` only), and that the `risk_band` filter is actively refused at that tier. These are non-obvious behavioral constraints an agent cannot get from the schema or 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 tight sentences: capability first, then return fields, then access constraints. Every sentence carries distinct information and nothing is padded or restated from 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?

There is no output schema, so the description correctly compensates by naming the headline fields returned per match. Combined with the access-tier and filter-refusal disclosures, an agent has enough to call this correctly and interpret the response, including the degraded case.

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 meaning the schema does not carry — specifically that the `risk_band` parameter is rejected for unauthenticated/free-tier callers, and that match records expose `score`, `risk_band`, and `subtype` as headline fields. That is genuine parameter-level nuance beyond the field descriptions.

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

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

The description states a specific verb and resource ("Search ACI providers") and enumerates the filter dimensions (free text, module, risk band, subtype). It is clearly distinguishable in kind from siblings like get_provider_detail or compare_providers, though it never names an alternative to route between them.

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 rather than stated: the agent can infer this is the discovery/list endpoint, but there is no explicit "use this when X, use compare_providers when Y" guidance. The access-tier notes describe behavior, not when to select this tool over its siblings.

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