jawz

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

The annotations already mark the operation as read-only and non-destructive, and the description adds further behavioral context: it does not log invocations, entitlement is required for non-open loops, and all published loops are currently open and free. This goes meaningfully beyond the structured 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 concise sentences, each carrying distinct value: the action, the entitlement caveat, and the logging distinction from run_chapter. No filler or redundant restatement of 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?

For a two-parameter read-only tool with an output schema, the description covers the essential context: what is fetched, how chapters are identified, entitlement rules, and the relationship to the logging variant. Nothing critical 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 input schema already covers both parameters fully, including an enum for node with descriptions. The description repeats 'loop slug and node' but adds no additional semantic detail, 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?

Description uses a specific verb ('Fetch') with a clear resource ('full content of a chapter') and identifies the two required identifiers ('loop slug and node'). It also distinguishes itself from run_chapter and get_loop by framing chapter-level content retrieval.

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 states when the tool is appropriate: fetching chapter content without logging an invocation. It names run_chapter as the alternative for running the framework and logging, and mentions entitlement conditions. This gives clear routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it is a public read requiring no auth, returns provenance fields (source URL, as_of_month, note), and duplicates data available elsewhere. It does not discuss caching or freshness beyond 'latest'.

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 action and payload, then the routing/context sentence. Slightly dense in the second sentence with a long nested path (get_financial_conditions.pillars.global_liquidity.components.china), but every clause earns its place by clarifying duplication and intent.

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 and full annotations, the description need not explain return values, and it still names the key fields. It covers sourcing, alternative access paths, and intended use, leaving no gap for a no-parameter read 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?

The tool takes zero parameters, so there is nothing to disambiguate; the baseline of 4 applies. The description correctly implies a no-argument read, and the enumerated return fields are extra value even though they belong to the output 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: 'Read the latest Mako-curated PBoC balance-sheet publication,' and enumerates what is returned (CNY trillions, source URL, as_of_month, note). It explicitly distinguishes itself from siblings by noting the value is also embedded in get_financial_conditions and get_dashboard, so an agent knows exactly what this tool uniquely provides.

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?

Tells the agent when to use it ('suitable for surfacing directly when explaining the China leg of global liquidity') and why it exists versus the alternatives ('direct/auditable access' vs. the embedded copies). It does not state an explicit when-not-to-use, but the overlap with get_financial_conditions/get_dashboard is clearly delineated.

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 readOnly/non-destructive annotations, it discloses provenance tagging ('observed' live vintage vs 'reconstructed' point-in-time, ~4 months deep), default window (12 weeks weekly), and response shape (data.rows, summary.deltas, presentation.display_markdown). 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?

It is long, but front-loaded with the core identity and each subsequent sentence adds distinct value (pillars, provenance, routing). A few clauses (the full pillar enumeration) border on surplus for a routing decision, keeping it off 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?

With an output schema present, return-value explanation is optional, yet the description still orients the agent on rows, summary.deltas, events, and the presentation object, while covering scope, defaults, and provenance. Nothing needed 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% — both interval and lookback_weeks already document cadence and the 1–52 clamp. The description restates the defaults ('last 12 weeks, weekly') without adding syntax or semantics 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?

Opening clause 'Financial-conditions read-history — a timeseries of how conditions have moved over recent weeks' gives a specific verb+resource+scope. It explicitly distinguishes itself from siblings get_regime_history (the judgment), get_liquidity_history (the flow), and get_indicator_history (any card over a year). An agent can route 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?

States the context of use ('grounds tightening statements in observed pillar changes', surfaces trajectory a point read hides) and names the alternative get_indicator_history with its distinct coverage. It does not spell out an explicit when-not condition, so it falls just short of a full routing rubric.

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/openWorld/destructive, but the description goes well beyond them: read-only and no account needed, three return renderings (structured content, markdown card, PNG image), error behavior for out-of-window dates, and nuanced point-in-time semantics including the specific rows that are not point in time and the point_in_time_note. That is substantial disclosure the 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?

The opening sentence and the card enumeration are front-loaded and every clause carries substantive information about badges, rows, and dated reads. It is, however, long and somewhat prose-heavy, and the explanation of the three return renderings partially duplicates the output schema, costing a point on tightness.

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

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

For a high-complexity, multi-card tool with an output schema and clean annotations, the description covers purpose, routing, dated-read semantics, caveats, and error behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single as_of parameter is documented, yet the description adds real meaning beyond it: the 365-day reach, exclusion of today as the default, the error on future/too-old dates, rules_note behavior, per-row point_in_time, and the Investment card's Data centres/Chips exception. This is more than the schema conveys.

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

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

The description names a specific resource (the Jawz Dashboard) and enumerates exactly what it contains: six readings (Regime, Money, Business cycle, Financial conditions, Store of value, Investment) with their badge vocabularies and per-card rows. It explicitly differentiates itself from sibling detail tools (get_macro_regime, get_financial_conditions, get_growth_indicators, get_inflation_indicators, get_indicator_history), so an agent can route correctly 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 clearly routes: this tool gives the overview, while the named siblings give 'the detail behind the cards' and get_indicator_history gives a card or row over time. It also states when as_of applies and its constraints. It does not spell out explicit exclusions beyond the date-window error, 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it reports on ALL sources, surfaces pipeline lag and plain-language notices about missing scheduled updates. It does not cover caching, latency, or staleness thresholds, keeping it short of a 5.

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

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

Two sentences, front-loaded with the resource scope and then the usage trigger. The middle clause enumerates output fields that the output schema already documents, which is mild redundancy, but the sentence still reads efficiently and wastes little.

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

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

For a zero-parameter, read-only diagnostic tool with an output schema present, the description supplies everything an agent needs: what it reports, that coverage is all sources, and when the result matters. Return-value detail is a bonus rather than a necessity here.

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 no parameter semantics to explain and the baseline is 4. The description correctly avoids inventing arguments and instead spends its words on the returned content.

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 resource and scope — freshness status for every data source Jawz reads — and enumerates the exact contents (release date, latest observation date, cadence, age, stale/unavailable flags). An agent can distinguish it from get_weekly_data_releases (scheduled release calendar) or get_drift_alerts (model drift) 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 triggering condition: use it when the reliability of a figure depends on how current its underlying data is. That is a clear context for selection, though it does not name alternatives or state when the tool is unnecessary.

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

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

Annotations only declare readOnlyHint and destructiveHint, so the description carries the load for behavior. It discloses that the tool iterates Decision Records, calls score_position_drift per record, returns specific fields, and explains the nuanced semantics of each flag type (e.g., fit_low_structural is low by design, not decay). This far exceeds what annotations provide and adds no contradictions.

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 dense but every sentence earns its place: the first sentence front-loads the core purpose and return values, and the flag-type list provides essential interpretation context. No filler or redundancy; the structure makes a complex behavioral contract digestible.

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 scanner with an output schema, the description is complete: it explains the input (portfolio of Decision Records), the process (iterating and scoring), the output semantics (flag types and accompanying fields), and the operational context (backing Mode 4.3 and feeding Mode 4.2). Nothing critical for correct invocation or interpretation 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 schema already defines portfolio as an array of Decision Records with field-level descriptions. The description adds some contextual meaning by saying it iterates and calls score_position_drift, but the parameter semantics themselves are largely already documented in 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?

The description states a specific verb ('portfolio-wide drift scan'), a clear resource (Decision Records), and the output (flagged positions with severity + why_flagged + review_questions). It also enumerates the exact flag types, making the tool's function unambiguous and easily distinguishable from its sibling score_position_drift.

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 frames this as the portfolio-wide scan and references Mode 4.3 (Thesis Status Sweep) as its use case, plus mentions it calls score_position_drift on each record, implying the single-position alternative. However, it does not explicitly state 'use score_position_drift for a single position' or provide a when-not-to-use exclusion, 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 mark this as read-only and non-destructive, and the description adds substantial behavioral context beyond that: data can be 'live' or a dated 'catalog' snapshot, holdings are TOP-N so exposure is a floor, bond/commodity ETFs return no holdings by design, and unknown tickers are surfaced in unknown_tickers. This is rich, accurate, and non-contradictory.

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, each carrying distinct value: the use case, the source/data freshness distinction, the TOP-N limitation, and edge-case behavior. The most important information is front-loaded and the description is efficient without being terse.

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 tool with a single parameter and an output schema, the description covers the essential operational details: purpose, data provenance, freshness semantics, coverage limitations, and unknown-ticker behavior. Nothing critical is missing for an agent to invoke and interpret the tool 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?

The schema already documents the sole parameter (tickers) with examples, so the baseline is 3. The description adds meaningful semantic value by explaining how unknown tickers are handled, that only top-N holdings are returned, and that certain ETF types yield no holdings—all directly relevant to using the parameter correctly.

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

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

The description clearly identifies the tool's function: ETF look-through that returns top holdings and weights for concentration checks. It distinguishes itself from the broad set of sibling 'get_' tools by specifically targeting Chapter 2 Mode 2.2 and by explaining why it exists.

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 usage context: this is for the Concentration Check in Chapter 2 Mode 2.2, and explains how the AI should use it to overlay holdings with direct positions. It does not explicitly name alternatives or when-not-to-use, but the context is strong and no sibling tool competes directly.

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, and the description adds substantial behavioral detail: consensus: null means unpublished rather than zero, results carry provenance fields, unsupported event types return empty lists with a staleness flag rather than silence, and coverage ends at a fixed date with a flag. No contradiction exists.

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 long but information-dense, with the core purpose front-loaded in the first sentence. Some redundancy with the schema and heavy use of caveats make it less crisp, but each behavioral note earns its place given the tool's edge cases.

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 covers the non-obvious behavioral context: null consensus semantics, provenance fields, fixed coverage horizon, unsupported event types, and deferred pricing. An agent has enough context to invoke the tool correctly and interpret surprising empty or flagged results.

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 parameters and defaults. The description reinforces event_types semantics and explains the empty-list behavior, but adds little new meaning for lookahead_days. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description states a specific verb and resource: getting scheduled US macro events (FOMC, CPI, NFP, PCE) with dates and consensus. It clearly differentiates the tool through explicit coverage constraints, so an agent understands what this calendar does and does not contain.

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 does not name sibling alternatives, but it gives clear selection guidance by specifying which event types are tracked and which are accepted-but-empty, and by noting that market-implied pricing is a separate deferred quantity. This tells an agent when to expect meaningful results and when not to use the tool.

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, so the description correctly spends its words elsewhere: it discloses that PBoC inclusion depends on a fresh Mako-curated publication (basis 'g4' vs 'g3'), that us_net_liquidity is 'a supporting read, not part of the regime light', and that scope/scope_note carry provenance. This is substantive 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 description is effectively one enormous sentence stitched together with em-dashes and nested parentheses, and much of it (the us_net_liquidity formula, change_decomposition method) describes return-value internals that the existing output schema already covers. It is front-loaded on purpose but far heavier than a single-parameter read tool needs.

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

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

With an output schema present, the description is not obligated to explain return values, yet it goes further and clarifies scope semantics, China provenance, and the summary_only shortcut. Coverage is strong; the only miss is not positioning the tool against overlapping siblings like get_liquidity_history.

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?

There is only one parameter and schema description coverage is 100%, so the schema already documents summary_only's boolean meaning. The description adds only that the lightweight read is 'used in regime composition', which is marginal value over the schema text; 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?

The opening clause names a specific verb and resource ('Full financial conditions read') and immediately anchors it to concrete outputs (the Money/Financial conditions cards of get_dashboard and the regime's Money row). It enumerates the exact pillars returned (global liquidity, real yield, credit spreads, DXY, VIX), which makes it unmistakable against siblings like get_china_liquidity, get_liquidity_history, or get_macro_regime.

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 only genuine usage steering is 'Pass summary_only:true for the lightweight one-line read used in regime composition', which tells the agent when to use the flag variant but not when to prefer this tool over siblings such as get_liquidity_history or get_china_liquidity. There is no explicit when-not guidance, so usage 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 cover the read-only, closed-world safety profile, and the description adds real value on top: GDPNow 'is reported, not scored, so it does not move the classification', missing estimates report status: unavailable rather than zero, and read_complete goes false when a series fails. These are non-obvious behaviors an agent would otherwise have to guess.

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

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

The purpose is front-loaded, but the body is a dense run-on block stitched together with semicolons and parentheticals that is hard to scan. Most content earns its place, yet the structure obscures more than it needs to for a description this long.

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

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

For a no-arg, output-schema-backed tool, the description is unusually complete: it names the blocks returned, the classification score separate from the vote, the staleness_flags behavior for missing estimates, and the read_complete failure signal. Nothing needed to interpret or invoke the tool is missing.

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

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

Zero parameters, so the baseline is 4. The description goes further by naming the underlying series codes and derived quantities (four-week average vs twelve weeks earlier, year-on-year A679RX1Q020SBEA), giving context for the returned fields even though no invocation arguments exist.

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 ('Growth pillar indicators') and immediately locates it in the tool hierarchy as the detail behind get_dashboard's Business cycle card and the regime's Mood row. The constituent series and the growth_vote_inputs block are named, so an agent can distinguish it from get_macro_regime and get_dashboard 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 through the relationship statements ('applied in get_macro_regime', 'the detail behind the Business cycle card of get_dashboard'), which positions the tool but never says explicitly when to reach for it versus those siblings. No when-not or prerequisite guidance is 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 establish readOnly=true, destructive=false and closed-world, and the description layers on substantial extra behavior: 365-day reach (store of value 84 days later), clamping echoed as requested_from/effective_from, partial:true with pending_from on a cold window plus resumability, and error naming of valid keys. These are exactly the operational traits annotations 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 purpose is front-loaded, but the body is a dense run-on wall of text with repeated phrasing ('Jawz's word' three times) and substantial output-shape detail that an existing output schema would already carry. It is informative but not tight; several clauses could be cut or deferred to 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?

For a zero-required-parameter, query-style tool with an output schema, this covers everything an agent needs: catalogue mode, parameter defaults and clamping, error conditions, partial-result/resume semantics, and the special handling for computed badges versus passed-through published series. Nothing decision-relevant 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 already 100%, but the description adds genuine meaning beyond the schema: 'to' defaults to today and 'from' to one year prior, the window is clamped to 365 days, and the badge/indicator interaction governs whether a card badge or a specific row is returned. This goes past the baseline 3 by supplying defaulting and clamping semantics the schema only sketches.

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

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

The opening clause states a specific verb+resource: any card of the Jawz Dashboard or one of its rows, over time, plus the no-argument catalogue mode. This is far more than a restatement of the name, but it never reconciles itself against closely overlapping siblings such as get_regime_history, get_conditions_history and get_liquidity_history, so an agent cannot tell from the text why it should pick this generic tool versus those per-domain ones.

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 conditional behavior for argument combinations: no args returns the catalogue, card alone returns the badge, card plus indicator returns the row, and it explains that unknown keys or out-of-window/future dates produce an error naming valid keys or range. It stops short of naming alternatives or stating when this tool should be preferred over the domain-specific history 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that it returns a classification (supportive/neutral/headwind), but says nothing about freshness, caching, or failure modes; with an output schema present, partial return detail is expected, so a 3 is appropriate.

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?

One dense sentence that front-loads the resource identity before listing contents and the return classification. Every clause carries content, though the long comma-separated series list makes it slightly harder to scan than a shorter statement would be.

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 an output schema present, the description only needs to convey scope and framing, which it does by naming the indicator families and the dashboard location it complements. Minor gaps remain — no cadence/freshness note and no explicit statement that no filtering is possible — 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?

There are zero parameters, so the baseline of 4 applies — there is no parameter semantics to explain or omit. The description correctly spends no effort on arguments and instead characterizes the payload.

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

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

States a specific resource (inflation pillar indicators) and enumerates the exact series covered — headline/core CPI, headline/core PCE (YoY/MoM), 5Y/10Y breakevens, wage growth. It also anchors itself against siblings by identifying it as the detail behind the Prices row of get_dashboard, so an agent can distinguish it from get_growth_indicators and get_prices.

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 phrase 'the detail behind the Prices row of the Business cycle card of get_dashboard' tells the agent exactly when this tool is the right drill-down rather than a sibling. There is no explicit when-not or mention of an alternative drill-down tool, 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 only declare read-only/closed-world, so the description adds substantial behavioral context: the g4↔g3 basis-flip coverage caveat (~$7T China component), the separate China-leg publication step (~15 days in arrears), provenance tagging ('observed' vs 'reconstructed', ~4 months deep), and a 'presentation.display_markdown' object. This is well beyond what the structured fields convey.

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

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

The core identity is front-loaded in sentence one, and most of the length carries genuine domain caveats an agent needs. However the passage is dense and somewhat repetitive (the coverage-change-vs-liquidity-move point is restated), so it is not maximally 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?

For a complex, multi-series tool, the definition covers scope, defaults, provenance semantics, event distinctions, and caveats; since an output schema exists, return values need not be spelled out, yet the key shape (rows/summary/presentation) is still noted. 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% with both parameters documented in-schema, so the baseline is 3. The description only restates the defaults ('last 12 weeks, weekly') already in the schema and adds no format or edge-case detail for interval or lookback_weeks.

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

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

The first sentence states a specific verb+resource+scope: a timeseries of central-bank liquidity over recent weeks, returning one row per sample date with named fields (Fed/ECB/BoJ/PBoC, basis, classification, us_net_t). It explicitly distinguishes itself from siblings, routing the held-money condition to get_macro_regime/get_dashboard and broader coverage to get_indicator_history, and labels itself the history companion to get_financial_conditions.

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

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

It gives clear context (history companion to get_financial_conditions; default last 12 weeks weekly) and names the alternative for other data (get_indicator_history covers any card/row over a year). It stops short of an explicit when-not rule, but the routing between this tool and its siblings is easy to infer.

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 indicate readOnlyHint=true and destructiveHint=false, and the description adds valuable context beyond those: it clarifies the return scope (no chapter content) and access rules ('all active loops are navigable by anyone'). This gives an agent useful behavioral expectations without redundancy.

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

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

Two tight sentences that front-load the main purpose and immediately specify key limitations and access. Every clause adds value; no filler or unnecessary 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?

Given the single required parameter, a rich output schema, and read-only annotations, the description provides everything an agent needs: what it returns, what it excludes, and who can use it. The mention of 'active loops' adds an important boundary condition. No significant gaps.

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

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

The schema already documents loop_slug with a clear example ('jawz'), and description coverage is 100%. The description only reinforces that the lookup is 'by slug' without adding new meaning or constraints, so it meets the baseline but does not exceed it.

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

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

Description uses specific verb 'Get' and resource 'metadata and chapter manifest for a loop by slug,' clearly stating what the tool returns. It explicitly notes it returns 'loop info and the list of chapter nodes with titles — no chapter content,' which differentiates it from content-returning tools like get_chapter.

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 clear context: this tool is for metadata and titles only, not chapter content, and states that 'all active loops are navigable by anyone,' addressing access. It implies the alternative of using a content-focused tool but does not explicitly name one, 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 cover the safety profile (readOnly), so the bar is lower, and the description far exceeds it: it discloses the hysteresis rules (regime changes only after two consecutive agreeing weekly reads, cycle after two agreeing prints), which fields carry raw reads vs. held state, and the exact response shape including a PNG image block after the 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?

Front-loaded with the core answer (what the regime is) before the mechanics. The single dense paragraph is long but each clause carries real information (hysteresis rules, field mappings, presentation layout), with only mild redundancy between the display_markdown/tables/data enumeration.

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?

Output schema exists, yet the description goes further and maps the response layout (card markdown, data.read, PNG content block, below-card write-up and tables, provenance block). Nothing an agent needs to interpret or invoke this zero-arg tool is missing.

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

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

Zero parameters, so the baseline is 4. The schema is empty and the description correctly spends no effort on arguments, focusing instead on output 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 specific verb+resource (get the macro regime) and immediately defines its outputs (GREEN/YELLOW/RED regime, SPRING/SUMMER/FALL/WINTER cycle). It explicitly distinguishes itself from siblings by calling itself the detail behind get_dashboard's Regime/Business cycle cards and by routing time-series questions to get_indicator_history.

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?

Names the related siblings and their boundary: this tool is the detail behind get_dashboard's cards, while get_indicator_history gives the regime/cycle or their rows over time. It stops short of an explicit 'use this when X, not Y' conditional, but the routing context is clear enough for correct selection.

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

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

Annotations declare readOnly/openWorld/non-destructive, yet the description adds substantial behavior beyond them: contradictory hints are reported rather than silently overridden, asset.isin is only filled from a hint or provider profile (never looked up), bare-ticker vs token ambiguity is resolved with explicit rules, and line/top-level warnings are described. This is unusually rich disclosure for a read-only tool.

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

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

Purpose is front-loaded and every clause is substantive, but the body is dense and parenthetical-heavy (e.g. the enumerated tokenized-stock proxies), which strains readability for a definition of this length. It earns its space on content but could be tightened structurally.

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?

Even though an output schema exists — which would relieve the description of return-value duty — it still describes the response shape (resolution, quote, fx, per-holding warnings) and closes the resolution-ambiguity cases an agent would otherwise get wrong. Nothing needed 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 would be 3, but the description adds cross-cutting semantics the schema does not carry on its own: how hints interact with each other and the result, that base_currency defaults to USD while 'native' returns unconverted quotes, and how a mismatched hint surfaces in resolution.mismatch.

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 ('Live prices for one or more holdings') and immediately scopes the return: price, value, day change per symbol plus per-holding resolution/quote/FX detail. It is unmistakable against siblings like get_etf_profile or get_macro_regime, none of which price holdings.

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 strong conditional guidance on how to invoke it correctly — qualify a ticker as NASDAQ:X / X.US to force a US listing, use asset_class 'equity' to override a same-symbol token, pass isin/exchange hints to narrow resolution. It does not name a sibling alternative or state an exclusion, but no sibling overlaps its function, so the remaining gap is minor.

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 safety profile (readOnly, non-destructive, closed-world), and the description goes well beyond them: provenance tagging of 'observed' vs 'reconstructed' rows with the reconstruction depth limit, method events in data.events, liquidity_events that explain non-market column steps, and the shape of the returned presentation/data/summary objects. This is exactly the extra 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?

The scope and return shape are front-loaded, but the body runs long for a 2-parameter tool. Dated illustrative examples (the 2026-09-25 money-condition rule, the 2026-09-30 growth vote) and the extended liquidity digression could be trimmed without losing selection-relevant 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 the description is not obligated to explain return values, yet it still maps the response objects and provenance semantics thoroughly. Nothing an agent needs to call this correctly — cadence, lookback, provenance caveats, alternatives — is missing.

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

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

Schema coverage is 100% and the schema already documents both parameters including their defaults and the 1–52 clamp, so the baseline is 3. The description restates the defaults ('last 12 weeks, weekly') but adds no new syntax or constraint beyond what the schema already says.

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 regime read-history timeseries) and enumerates exactly what each row contains (colour, quadrant, growth/inflation class, sentiment, liquidity, risk, confidence) plus transitions. It actively distinguishes itself from the two nearest siblings, get_liquidity_history and get_indicator_history, so an agent can route without opening any schema.

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

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

Gives a clear selection condition — use this for the observed history behind a 'what changed since …' question, not for comparing two point reads — and names get_liquidity_history as the alternative when a constant-basis G3 series is needed. It stops short of a crisp when-not rule (e.g. when to prefer get_macro_regime or get_conditions_history), so a 4 rather than 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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral fact beyond that: the output includes a live market read drawn from the current data layer, signaling dynamic content. It says nothing about auth, limits, or freshness caveats.

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, which is good, but everything is packed into a single long run-on sentence with a nested parenthetical and six-item return enumeration that is taxing to parse. Content largely earns its place, but the structure could be split for 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?

With zero parameters, safety annotations, and an output schema already present, the description need only establish purpose and usage, which it does. The detailed list of returned fields duplicates the output schema somewhat rather than adding new information.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies a no-argument onboarding call and adds no misleading parameter expectations.

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 (orientation for a new Jawz connection) and enumerates exactly what the tool covers: what Jawz is, what it covers, how it is used. It explicitly distinguishes itself from siblings by naming get_dashboard as the downstream starting point and describing the Jawz Loop as separate content, so an agent can route correctly 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?

The description gives a clear trigger condition ('for questions about what Jawz is, what it covers, or how it is used') and points at get_dashboard for the state of the world. It does not state explicit when-not-to-use cases or contrast with get_loop/get_chapter, so it stops short of full alternative routing.

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

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

The description goes well beyond the readOnly and destructive annotations by explaining classification semantics, the difference between surprise and vs_consensus, the directional meaning of hot/cool, the n/a case, and the provenance age measurement behavior. This is exactly the behavioral context an agent needs to interpret results correctly.

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 dense but every sentence earns its place by preventing misinterpretation. It front-loads the core resource and timing, then explains output semantics and edge cases without redundancy or 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?

For a single-optional-parameter read-only tool with an output schema, the description is highly complete. It covers timing, absence semantics, field explanations, interpretation pitfalls, and idempotent behavior. Nothing essential for correct invocation or result interpretation appears missing.

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

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

Schema coverage is 100%, and the schema already documents week_ending format and default. The description adds meaningful parameter-adjacent semantics: the Friday anchoring, the freshness caveat, and the fact that consensus_provenance.age_days is measured at week_ending rather than call time. This goes beyond the baseline but does not redefine the parameter 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?

The description clearly identifies the resource: past week's data releases with an H.4.1 net liquidity update. It is specific about scope and timing, but it does not explicitly contrast itself with sibling tools such as get_event_calendar or get_data_health, so it stops short of full sibling differentiation.

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

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

It provides clear usage context by stating the tool is anchored to Friday and most current when run Friday morning or later. It also advises that re-asking for an earlier week yields stable age_days values. However, it gives no explicit when-not-to-use guidance or alternative tool 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 and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: default-to-latest behavior, slug format expectations, and list_only returning available editions without content, which goes beyond what the annotations convey.

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

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

The description is three sentences with no filler. It front-loads the core purpose, then efficiently covers default behavior, slug format, provenance of claims, and list_only mode. 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 this is a simple read-only retrieval tool with zero required parameters, a rich output schema, and clear annotations, the description covers everything needed: what it returns, how to select an edition, and how to list editions. No meaningful gap remains.

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, but the description adds meaningful detail: it specifies the YYYY-MM-DD slug format, confirms omission yields the latest, and explains that list_only excludes content. This enriches the parameter semantics beyond the schema alone.

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 ('Read') and a specific resource ('Jawz World Brief'), immediately distinguishing it from all 21 sibling getters. It also clarifies the default behavior and the key option, leaving no ambiguity about what the tool does.

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 states when to fetch the latest edition versus a specific slug, and when to use list_only to retrieve editions without content. It does not explicitly name alternatives, but the tool is unique among siblings and the usage context is 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 readOnlyHint and destructiveHint, so the safety profile is known. The description adds valuable behavioral detail: it returns loop metadata, access status, and the active loop, states that every published loop is free and open, and explains that entitled deprecated loops appear with deprecated: true. This goes beyond the annotations without contradicting them.

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 concise sentences, each adding distinct information: the primary listing purpose, the return contents, and the deprecated-loop nuance. No filler or redundancy. The key facts are 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?

For a zero-parameter listing tool with an output schema present, the description is complete. It covers the main use case, access semantics, current-active-loop information, and deprecated-loop behavior. Nothing essential is missing.

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

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

The tool has zero parameters and the schema is empty, so there is no parameter documentation burden. The baseline for zero parameters is 4, and the description appropriately focuses on the output and behavioral aspects rather than parameter details.

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

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

The description clearly states the tool's verb ('List') and resource ('all available Jawz loops'), and specifies the scope: metadata, access status, and the currently active loop for the user. This distinguishes it from the sibling get_loop, which presumably fetches a single loop, by focusing on collection-level listing.

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 context is implied but not explicit. The description implies this is the tool to call to enumerate available loops and see which is active, but it does not name alternatives or state when to prefer list_loops over get_loop or run_mode. The guidance is sufficient for a zero-parameter read-only listing, but lacks explicit 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?

The description discloses important behavioral traits beyond the annotations: repeated calls return identical content rather than regenerating text, each call appends a usage-counter row, and each call returns a new invocation_id for feedback. This is exactly the kind of side-effect and determinism information an agent needs and that annotations do not provide.

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

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

Four sentences, no filler, primary behavior first, side effects after. Every sentence adds useful information and the structure makes the most important details immediately visible.

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

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

The description covers what the tool returns, its stable/cached behavior, its side effect, and the invocation_id usage. An output schema is present, so return details do not need to be fully explained. The main gap is that loop_slug and node parameter semantics are left shallow, and no explicit comparison with get_chapter is provided.

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. However, the schema descriptions are minimal: 'Loop slug', 'Chapter node', and 'Optional user context' add little real meaning. The tool description also does not explain how loop_slug and node relate to the returned framework text, nor what each node enum value means. It earns the baseline but no more.

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: 'Returns a chapter's published framework text' and lists what that text contains (modes, questions, output format). This is much clearer than the tool title alone. It does not explicitly differentiate itself from the sibling get_chapter, so it loses a point for sibling distinction.

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 intended use: the framework text is reference material for the assistant to apply when judging appropriately. This tells an agent why it would call the tool. However, it does not mention when not to use it or compare it with alternatives like get_chapter or run_mode.

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

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

The description discloses behaviors beyond the annotations: repeated calls return identical content (not regenerated), each call appends a usage-counter row, and each call returns a new invocation_id for feedback. This is valuable operational context that annotations do not provide.

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

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

Three sentences, each earning its place: one for what is returned, one for idempotent behavior, one for side effects and feedback linkage. No fluff, no repetition of schema content, and the most differentiating 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?

The description covers the core behavior, the side effect, and the deterministic nature of the tool. An output schema exists, so return-value details are not required. It could additionally mention prerequisites or explicit alternative conditions, but nothing essential for calling the tool 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 all parameters. The description reinforces the 'mode' concept and the granularity of the call, but it does not add parameter-specific detail beyond what the schema's descriptions and enum already provide. 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?

The description states a specific verb ('Returns') and a precise resource: 'published framework text for one named mode within a chapter.' It also distinguishes itself from fetching the full chapter, which separates it from the sibling run_chapter. The purpose is immediately clear and unambiguous.

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 frames when this tool is appropriate: when a single mode's text is needed rather than the entire chapter. It does not explicitly name sibling alternatives or state when not to use it, but the 'rather than the full chapter' contrast provides solid contextual 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 mark the tool as read-only, and the description adds meaningful behavioral context beyond that: the output is observational, contains no buy/sell recommendation, and includes drift labels and review questions. This gives an agent an accurate model of what the tool will and will not do, without contradicting 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?

The description is three sentences with a front-loaded purpose and no filler. The explicit list of output fields is slightly redundant given the declared output schema, but it is compact and useful enough to justify a high score.

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 read-only annotations, a fully documented schema, and an output schema, the description is complete: it explains what the tool scores, which modes it supports, what type of output to expect, and that it is observational. No critical operational information is missing.

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

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

Schema description coverage is 100%, so all six parameters are documented with types, enums, and descriptions. The tool description adds little parameter-level meaning beyond 'single position' and 'since entry', so the baseline of 3 is appropriate.

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

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

The description identifies a specific verb and resource: score how a single position's regime fit has drifted since entry, and enumerates the returned fields. It is clear and actionable, but it does not explicitly contrast the tool with sibling get_drift_alerts or get_regime_history, so differentiation relies on name and context rather than an explicit 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?

The description gives clear context: it supports Chapter 4 Mode 4.2 for single-name retrospective review and Mode 4.3 for per-position drift across the book, and explicitly states that no buy/sell recommendation is made. It lacks explicit exclusions or named alternatives, but the mode references and observational caveat provide enough guidance for an agent to decide when to use it.

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