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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description earns credit by spelling out what idempotency means here ('returns the first acknowledgment unchanged, preserving the true responder and time') and by warning that the operation has a side effect (stopping the escalation clock) without resolving anything. It does not mention permission requirements or who may acknowledge, which is the remaining gap.

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

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

Three sentences, each doing distinct work: what the tool does, what it does not do, and how repeat calls behave. The scope/effect statement is front-loaded ahead of the idempotency detail.

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

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

An output schema exists, so return values need no explanation, and the description covers the mutation's semantics and its limits completely. The only unaddressed complexity is the set of projection parameters (detail, limit, since, symbols, include_withheld), which are left entirely to the schema.

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

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

Schema description coverage is 88%, so the schema already documents incident_id, note, acknowledged_by, and the projection controls; the description adds no parameter-level meaning at all. Baseline 3 applies — nothing misleading, but nothing additive either.

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 precise verb and resource ('Record that an incident has been seen') and immediately scopes it against the two things an agent would confuse it with: closing an incident and issuing a verdict. That makes it distinguishable from the many sibling read tools and from the verdict/history tools 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 a clear trigger ('record that an incident has been seen') and an explicit exclusion ('does NOT close the incident', 'asserts nothing about whether the risk passed'), routing resolution work elsewhere. It stops short of naming the sibling verdict tools by name, so the agent must infer which call actually resolves the incident.

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 safety (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real context: stored thresholds are not applied, legacy hold/watch/reduce labels are non-binding priority only, and nothing here authorizes portfolio or order action. It does not add pagination or rate-limit behavior, keeping it from a 5.

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

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

Purpose and outputs are front-loaded in the first two sentences, and the threshold/authorization caveats follow logically. The final sentence partly restates the 'does not apply stored thresholds' point about fahali_get_portfolio_decision, but it is dense rather than padded.

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

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

With an output schema present, return values need not be spelled out, and annotations plus a 100%-covered schema carry the rest. The description supplies the key semantic caveats (no thresholds, non-binding labels, monitor-only, no authorization) so an agent can call it correctly; only explicit input-shape guidance is thin.

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

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

Schema description coverage is 100% and the schema itself explains the symbols-vs-positions tradeoff and the detail/limit defaults. The description adds essentially no parameter guidance beyond mentioning a 'requested-book covariance matrix', 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 ('Analyze measured risk for a custom inline portfolio') and enumerates the concrete outputs (VaR/expected shortfall, detection-risk observations, direction reconciliation, covariance matrix). The 'custom inline' qualifier distinguishes it from stored-portfolio siblings like fahali_get_portfolio_risk and fahali_get_portfolio_metrics.

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

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

Explicitly says it does not apply stored monitoring thresholds and names fahali_get_portfolio_decision as the alternative that adds durable thresholds. This gives a clear use-vs-alternative signal, though it never states the positive trigger (e.g. 'use when you have an ad-hoc position list not saved as a watch').

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

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

Goes well beyond the annotations by disclosing real side effects: alerts surface in the in-app realtime feed, are prefixed with agent_ so they cannot be mistaken for engine detections, do not fan out to push/SMS, and severity is capped at high. This is exactly the kind of consequence an agent needs before writing. It omits the idempotency_key retry behavior, which lives only in the schema, and does not describe what the call returns.

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

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

A single compact paragraph with the core action front-loaded and each clause carrying distinct behavioral content (feed visibility, prefix, no push/SMS, severity cap). Dense but no filler; slightly long as one unbroken sentence.

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 11 parameters at full schema coverage and an output schema present, the description does not need to explain params or return values. It covers the key behavioral risks (visibility, notification fan-out, severity ceiling) well; the only meaningful gap is the absence of usage routing toward related read 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?

Schema description coverage is 100%, so parameters are already fully documented, including the severity enum rationale and idempotency_key semantics. The description restates the severity cap that the schema also explains, adding emphasis but not new parameter-level information. 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?

Opens with a specific verb and resource: 'Create a custom alert.' That is unambiguous and distinguishable from the read-only alert siblings such as fahali_get_realtime_alerts. It stops short of naming alternatives or stating scope constraints an agent would use for routing.

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 'Create a custom alert' and the agent-oriented framing, but there is no explicit when-to-use / when-not-to-use guidance, no mention of prerequisites, and no routing to sibling tools (e.g. reading alerts via fahali_get_realtime_alerts). An agent can infer intent but is not steered.

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, idempotent, non-destructive and open-world, so safety is covered; the description adds payload-size intent and the shape of the response. However, it claims the tool is lightweight 'without a large payload' while the schema's `detail` parameter defaults to `audit` (described as full-fidelity), and the description never reconciles that — an agent following the prose alone would get the opposite of what is promised.

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: purpose first, then return contents, then sibling routing. No filler and the most decision-relevant information is front-loaded.

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 re-explained. But for a tool whose entire selling point is a small payload, the description omits the one thing an agent must know to honor that: the `detail` default is `audit`, not `brief`, and `include_withheld` defaults to true, so the caller must override parameters to actually get the lightweight response described.

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 (limit, since, detail, symbols, include_withheld) with defaults and enum semantics. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

The description clearly frames the tool as a compact daily market orientation and enumerates what it returns (key change, why it matters, evidence quality, next actions). It names the two sibling tools it is not (market briefing, market verdict), so an agent can distinguish it without opening the schema. It falls short of a 5 only because the framing is payload-centric rather than a crisp verb+resource statement.

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

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

It explicitly routes the agent: use market briefing for depth, market verdict for named symbols, implying this is the default-shallow, symbol-agnostic entry point. There is no explicit when-not guidance (e.g. don't use this for a specific instrument question), but the alternatives are named and the selection condition is inferable.

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/idempotent/non-destructive, but the description adds the substantive behavior: the full six-value result taxonomy, the safeToRepeat flag, the non-obvious semantics of NO_READ (not agreement), and the aggregation rule that the worst assertion drives the summary. These are interpretive facts an agent cannot 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?

Four short sentences, front-loaded with the purpose, then the result vocabulary, then the decision rule. Every sentence carries new information—no restatement of the name 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?

With an output schema present and full schema coverage, the description covers the main interpretive burden (status meanings, safeToRepeat, summary aggregation). It leaves the ordering of 'worst' in the severity ladder implicit, which the agent must infer to predict the summary value.

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 six parameters (claim, limit, since, detail, symbols, include_withheld) are already documented, and the enum plus defaults are described inline. The description adds no parameter-level guidance of its own, so the baseline of 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 ('Verify a proposed market narrative') plus the scope condition ('before repeating it'). It reads as an assertion-level verification tool, clearly distinct from sibling verdict/decision tools like fahali_get_market_verdict or fahali_get_symbol_decision.

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 gating condition 'before repeating it' and the rule 'Only SUPPORTED is repeatable; NO_READ is not agreement' tell the agent exactly when the tool is applicable and how to act on results. It stops short of naming alternative sibling tools for nearby needs, so it is clear context rather than explicit 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 readOnly, idempotent, openWorld, and non-destructive. The description adds important behavioral context beyond annotations: listing does not imply entitlement, and a gated resource returns a refusal describing the credential rather than the 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 tight sentences, front-loaded with the core action and constraints. Every sentence carries a distinct operational rule with 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?

Annotations cover safety, schema covers all parameters in detail, and an output schema exists. The description completes the picture with the source-of-truth path requirement and the entitlement/refusal nuance, leaving no major ambiguity for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning by explaining the path_params/query mapping ('Supply :params via path_params, filters via query') and reinforcing that resource paths are not free-form URLs.

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 ('Fetch any catalogued Fahali resource by path') and immediately distinguishes it from siblings by tying the path source to fahali_list_resources. An agent can tell this is the generic catalogued-resource access tool.

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

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

Gives explicit constraints: path must come from fahali_list_resources, must be catalogued, never arbitrary URLs, never write routes. It does not explicitly say when to prefer specialized sibling tools, but the when/when-not guidance for this tool is strong.

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/idempotent/non-destructive, and the description adds substantial domain semantics on top: what opens an incident (REDUCE/EXIT or degraded evidence coverage), what closes it (a later verdict), and escalation on non-acknowledgement. The 'empty list means nothing is open, NOT that the market is calm' line is exactly the interpretive guardrail an agent needs and 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 compact sentences, front-loaded with the purpose, then lifecycle, then usage, then the caveat. The lifecycle sentence is dense but every clause (open condition, close condition, escalation) carries distinct information.

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

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

An output schema exists, so return values need no explanation, and zero required parameters means there is no calling precondition to state. The description covers definition, lifecycle and empty-result semantics; it omits any pointer to the detail/include_withheld projections, which materially change the payload but are documented in the schema.

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

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

Schema description coverage is 86%, so the schema already documents limit, since, detail, symbols, watch_id, include_resolved and include_withheld well. The description adds no parameter-level guidance of its own — notably it never clarifies how include_resolved interacts with the 'still waiting on' framing, which is the one ambiguity worth addressing. 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 ('List monitor-only incidents') with precise scope ('Fahali opened on your watches and is still waiting on'), which cleanly separates it from siblings like fahali_get_incident_timeline (history) and fahali_acknowledge_incident (mutation). An agent can identify the tool 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?

'Use it to find what you have not answered' gives a clear situational trigger, and the empty-list caveat prevents a common misread. It stops short of naming the alternative tools (e.g. acknowledge or timeline) for follow-up actions, so routing is implied rather than explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description is free to add genuine value: it is authenticated, views run in parallel, and failed views are named explicitly rather than silently producing a partial read. That failure-mode disclosure is exactly the kind of context annotations cannot convey.

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

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

Four front-loaded sentences with no filler; the core promise and the failure semantics come first and the detail guidance closes it. Minor tension: it calls the bundle 'compact' while the schema defaults detail to full-fidelity 'audit', which is slightly confusing in an otherwise tight statement.

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 needn't explain return values, and it covers what matters for correct invocation: view selection, defaults, depth tradeoff, and partial-failure behavior. The default mismatch between 'brief' advice and the schema's 'audit' default is the one unresolved wrinkle.

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 it by naming the default view set and by recommending the 'brief' depth over the schema's actual default of 'audit', which an agent would otherwise miss. It does not explain the symbols or since parameters, keeping it at 4.

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

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

States a concrete verb and resource — fetch a named set of market-intelligence views in a single response envelope — and the emphasis on bundling implicitly separates it from the many single-view siblings. It never names a specific sibling to avoid, so it stops short of a 5.

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

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

Gives explicit operating guidance: choose only the views needed, defaults are stated (market_decision, briefing, risk_score, regime, conviction), and 'use detail=brief unless raw evidence is required' is a clear conditional. No explicit when-not-to-use versus the individual getters, so not 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 read-only, idempotent, non-destructive, and non-open-world behavior. The description adds useful context beyond annotations: the call is local, lightweight, does not query market data, and compatibility-only names are dispatchable but absent from discovery.

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

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

The description is front-loaded with the key instruction ('Start here...'), followed by concise statements about what is returned and important caveats. Every sentence contributes useful routing or behavioral information without repetition.

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 a rich output schema, complete parameter documentation, and strong annotations, the description supplies the remaining context an agent needs: when to use it, what kind of catalogue it returns, and that it is local and does not query market data.

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 optional parameters in detail. The description itself only loosely gestures at 'response controls' and adds no parameter-specific syntax or defaults 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?

The description gives a specific verb and resource: it returns the canonical live tool catalogue, taxonomy, workflows, tier requirements, identity rules, and schema resources. It also clearly positions itself as the starting discovery/meta tool, distinguishing it from the many specific Fahali data tools in the sibling list.

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

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

It explicitly says to start here when planning an autonomous Fahali workflow, which gives strong usage context. It does not name exclusions or specific alternative tools, but the 'start here' framing is clear enough for 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 read-only, idempotent, open-world, non-destructive, so the safety bar is low; the description nonetheless adds substantive traits: the data is a candle-derived proxy, lacks aggressor tape and participant identity, and carries no forecast. It also pre-empts a likely misread of the payload ('Zero detector score does not erase netFlowUsd: the score measures unusualness, not data presence'), which is exactly the kind of value beyond structured fields that matters.

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

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

Three sentences, no waste, with the core capability front-loaded before the caveats. The zero-score caveat and the proxy-limitation sentence each carry distinct information an agent would otherwise have to discover empirically.

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 shape is covered by the output schema and safety by annotations, so the description's job is scope, defaults, and limits — all three are addressed. An agent can call it with no arguments, with symbols, and correctly interpret a zero score without further context.

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 adds the one thing the schema cannot convey — the semantic default when symbol/symbols are omitted (return the strongest available readings rather than nothing). It does not elaborate on limit/since/detail, but those are already fully documented in-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 measurement (60-minute USD order-flow imbalance) with the resource (symbols) and its default fallback behavior, so the agent knows exactly what it is retrieving. The closing disclaimers ('candle-derived proxy only; no aggressor tape, fund-flow attribution') sharply separate it from attribution/forecast-style 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?

'or the strongest available readings when none are supplied' tells the agent it can call with zero arguments and what happens then, which is real usage guidance. However, it never names an alternative sibling (e.g. fahali_get_unusual_money_movement, fahali_get_microstructure_proxy) or states when to prefer this tool over them, so the when-to-use-vs-alternatives dimension is left implied.

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, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real context — cases are verified/resolved, time-diverse, and sourced from a specific engine — but the fixed '40 cases' claim sits uneasily beside a limit parameter allowing up to 100, and the description never resolves whether 40 is a hard cap or a default.

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 prose is not padded, but the long field enumeration largely restates what the output schema already provides and crowds out higher-value information about when to use the tool. Roughly half the text is recoverable from the structured 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 an output schema present and full schema coverage on five parameters, the description only needs to establish what the data represents — which it does via 'verified', 'resolved', 'time-diverse', and the engine name. The one meaningful gap is the unresolved interaction between the stated 40 cases and the limit parameter.

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 limit, since, detail, symbols, and include_withheld in detail. The description adds only the implicit notion of a default sample size ('40 time-diverse cases') and says nothing about the detail projection levels or symbol projection semantics. Baseline 3 is appropriate.

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

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

Names a specific verb and resource ('Get verified case studies') and pins the source domain ('resolved signal-outcome moat'), plus names the producing engine ('walk_forward'). It is clear what the tool returns, but it never distinguishes itself from adjacent evidence/performance siblings such as fahali_get_track_record_scorecard or fahali_get_evidence.

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 over the many other signal/performance tools in the sibling list, and no exclusions. 'Verified' and 'resolved' hint that these are historically graded outcomes rather than live signals, but that inference is left entirely to the agent.

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 safety (readOnly, idempotent, non-destructive), and the description adds substantial interpretation context beyond them: arrow order and lagHours are precedence, not causation; most pairs lack a measured lag; propagation entries are flagged measured or composed; high/extreme requires repeated evidence. These are exactly the caveats an agent needs to avoid over-claiming causality from the 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?

Seven short sentences, each carrying information, with the core object stated first and no filler. It is telegraphic to the point of density (field paths like measurement.edgesWithMeasuredLag and symbolsEligible arrive without setup), which costs some readability but not length.

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 analytical tool with an output schema, the description covers what the schema cannot: causal-interpretation caveats, data-coverage warnings, field semantics for measured vs composed, and an alternative route. Return shape is left to the output schema, which is correct.

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 limit, since, detail, symbols and include_withheld fully. The description adds no parameter-level guidance at all – no advice on choosing detail levels or on the audit default – so it neither compensates nor detracts. 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 analytical object (one-hour lower-tail-dependence associations with a measured temporal layer) and its components (lead-lag graph, propagation, sampleSize), so an agent knows what it gets. It also names the sibling it is not (fahali_get_correlation_matrix for Pearson). It stops short of a clean single-sentence statement of the operation, which makes the first read harder than necessary.

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 routes the agent to an alternative with a condition: 'Requested-book Pearson: fahali_get_correlation_matrix.' It also sets an expectation about when the temporal layer is usable ('Check measurement.edgesWithMeasuredLag; most pairs have none'). It never states exclusions or prerequisites for calling this tool versus the other risk/verdict siblings, so the routing is narrow rather than complete.

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, idempotent, non-destructive, open-world behavior, so the description only needed to add context — and it does: the 45-day canonical covariance artifact, per-pair observation counts, alignment policy, and explicit missing coverage. Those are real behavioral traits an agent cannot get from the annotation block. It stops short of noting cost or latency characteristics.

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 dense sentences with no filler: the provenance/methodology claim first, then the interpretive boundary. Every clause carries distinct information and the most decision-relevant content is front-loaded.

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 100% schema description coverage, the description needn't explain return shape or defaults, and it correctly focuses on provenance and interpretive limits. It could still note that omitting symbols yields the fixed six-asset reference set, though that is covered in the schema.

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

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

Schema coverage is 100%, so all five parameters (including the oneOf symbols form, detail enum, and include_withheld default) are documented in structured data. The description adds only indirect meaning — 'requested-book' maps to symbols and 'explicit missing coverage' hints at include_withheld — 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 ('Pearson correlation ... from the canonical 45-day covariance artifact') with the data provenance and window, and explicitly disclaims contagion direction, which separates it from the nearby fahali_get_contagion_map 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 disclaimer 'Historical association only: not causality, future correlation, or a contagion direction' frames the interpretive scope, which implicitly signals when to prefer contagion or forecast siblings. However, no explicit when-to-use/when-not or named alternative is given, so routing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds epistemic scope by saying it 'measures what fired, not institutional identity, capital flow, or conviction,' which is genuinely useful context. It does not add further behavioral detail (aggregation window, ordering), so a 3 is fair with annotations doing heavy lifting.

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 before the caveat and next step. No filler. Some jargon ('evidence gate,' 'market verdict') but overall tight.

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

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

An output schema exists so return values need not be described, and annotations cover the safety profile. The description supplies purpose, scope, and a next step; only the sibling-routing usage guidance is thin. Complete for a read-only detection-summary tool.

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

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

Schema description coverage is 100%, so the parameters (limit, since, detail, symbols, include_withheld) are fully documented in structured data. The description adds nothing about how to set them. Baseline 3 is appropriate when the schema carries the semantics.

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 concrete verb and resource: recent detection activity per symbol with bullish/bearish alert counts. The second sentence explicitly distinguishes it from siblings by ruling out institutional identity, capital flow, and conviction, which maps to fahali_get_capital_flow and fahali_get_highest_conviction_signals. Clear enough to select it confidently.

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 third sentence describes a downstream step (use highest-conviction signals to apply the evidence gate and market verdict), not when to pick this tool over alternatives. Usage is implied by 'recent detection activity' but there is no explicit 'use this when / not when' routing. Adequate but leaves the selection boundary 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 read-only, idempotent, open-world, non-destructive, so safety is covered. The description adds real behavioral substance not in the annotations: the served `fit` block discloses whether probability is calibrated, unmeasured inputs mean missing data rather than calm, and withheld-only rows are surfaced via record.withheldOnly. That materially changes how an agent should treat the returned numbers.

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

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

The opening clause front-loads purpose well, and the interpretation cautions earn their place. However, the middle sentence enumerating added fields (findings[], matchedTrackRecord, recordMatchReason, ownStrataCount, record.withheldOnly) is partially redundant against the existing output schema and is ambiguous about what they are 'added' relative to.

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, full annotations, and 86% schema coverage, the description only needs to add the interpretive frame, and it does: calibration disclosure, missing-data semantics, stratum-over-headline reading. The main residual gap is the absence of any routing versus the engine_status sibling.

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 86%, so limit, since, detail, symbols, and include_withheld are already documented in the schema. The description only contributes the semantic that engine is a 'key' and that a `fit` block is included; it adds nothing about how symbol/symbols or detail interact with the board output. 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 concrete verb+resource ('board of any contract engine by key') and enumerates the payload components: live claims with probability, attribution, input census, health, judged record. An agent can tell it is an engine-level inspection tool, though it never distinguishes itself from the sibling fahali_get_engine_status, which sounds adjacent.

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 fahali_get_engine_status, fahali_get_market_decision, or other engine-related siblings. The closing advice ('read the own stratum, never the headline') is output-interpretation guidance, not selection guidance, and no prerequisites or exclusions are given.

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 readOnly/idempotent/non-destructive, so the description wisely spends its words on interpretation semantics: incomplete measurements are null, and zero only appears for a complete empty window and never proves an engine is down. That is genuinely useful context not present in annotations, though it omits what happens with withheld rows despite the include_withheld param.

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?

It is short and front-loaded, but the opening clause is a dense string of unexplained jargon ('event-gated, continuous, validation-only, retired, and structurally unattributed states') that costs readability without earning comprehension. Later sentences are tighter and more valuable than the first.

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 format need not be explained, and the description supplies the interpretive caveats an agent needs (nulls vs. zeros, dataState/freshness, liveness vs. skill). Remaining gaps are minor, such as the interaction between include_withheld and the 'withheld' liveness state.

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 every parameter carries its own documentation (limit defaults, detail enum semantics, include_withheld behavior), so the schema does the heavy lifting. The description adds no parameter-level guidance, which is acceptable at this coverage but not additive.

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

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

Names the resource concretely as engine liveness and enumerates the liveness states it distinguishes, and explicitly separates itself from the track-record scorecard ('liveness is not accuracy'). It does not, however, clarify how it differs from the close sibling fahali_get_engine_board, leaving some ambiguity in a crowded namespace.

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 direction: read dataState and freshness here, and go to the track-record scorecard for skill/accuracy questions. It states a when-not explicitly ('liveness is not accuracy'), though it says nothing about when to prefer the engine board or other status-adjacent siblings.

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 read-only, idempotent, non-destructive, so the safety profile is settled. The description adds substantive context beyond that: the snapshot is hashed at decision time and hash verification is returned, and 'explicit retention gaps' signals that missing data is a normal, disclosed outcome rather than an error. It does not discuss pagination or how large the retained event sets can get.

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 identity and followed by the contents and the one actionable usage rule. The middle sentence is a dense enumeration but each item earns its place; nothing is padded.

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

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

An output schema exists, so enumerating return fields is partly redundant, but naming hash verification and retention gaps tells the agent what to look for in the response. The main gap is routing: with this many adjacent verdict/evidence siblings, an explicit alternative would have closed the definition.

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 a moderate 63%, and the description reinforces the detail enum tradeoff rather than adding new syntax. Five parameters (limit, offset, since, symbols, evidence_ids, include_withheld) carry no guidance in the description, though symbols/include_withheld are documented in the schema itself.

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 ('Fetch the ... evidence behind one immutable portfolio verdict') with scope qualifiers: compact, content-addressed, single verdict. This clearly separates it from sibling tools like fahali_get_verdict_by_id (the verdict itself) and fahali_get_verdict_history (the list).

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

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

It gives a decision rule for the detail parameter ('summary for routine audit, full only when raw source metadata is required'), which is genuinely useful. But it never says when to reach for this tool instead of fahali_get_portfolio_decision, fahali_get_verdict_by_id, or fahali_get_bundle, all of which sit close to the same data.

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 a safe read (readOnlyHint, idempotent, non-destructive), so the bar is lower, and the description still adds real substance: calibration is disclosed via the served `fit` block, unmeasured inputs are framed as missing rather than calm, and "late" is explicitly not a claim. These are meaningful caveats an agent would not 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?

The core purpose is front-loaded, which is good, but the middle sentence is a raw enumeration of output field names (findings[], matchedTrackRecord, recordMatchReason, ownStrataCount, record.withheldOnly) that an output schema already covers, and the jargon density makes it slower to parse than needed.

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 semantically heavy risk-board tool with an output schema present, the description covers the conceptual burden well: what the probability means, that calibration is conditional, and how to read strata versus headline. Return-value detail is redundant but not missing anything an agent needs to invoke 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 description coverage is 83%, so the schema already carries most parameter meaning. The description adds nothing about limit, since, detail, symbols or include_withheld, leaving baseline 3 as the correct ceiling for this dimension.

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 the specific resource and horizon: an 8-hour fall-warning board with standing warnings at probability P of a >=5% drawdown within 8h, plus attribution, input census and judged record. That is far more specific than the name alone. It does not, however, explicitly distinguish itself from close siblings such as fahali_get_flash_crash_risk or fahali_get_market_risk_score.

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

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

Guidance given is about interpretation rather than selection: "read the own stratum, never the headline," "Unmeasured inputs are missing data, never calm." Those are useful directives, but there is no statement of when to call this versus the flash-crash or risk-score siblings, and no exclusion conditions.

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