American Default Research

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: quarterly update cadence, the 0-100 score range, the 1-5 band scale, and an instruction to quote rank_in_history.reading beside the band label. It stops short of describing error/no-data behavior.

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

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

Front-loaded with purpose and cadence, then a dense enumeration of returned fields. Given the absence of an output schema, the enumeration earns its length, though 'the methodology reading of the inputs' is vague enough to be dead weight as written.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does so thoroughly: composite score, band and label, historical rank, methodology reading, and all five domains with member component percentiles. Combined with annotations covering the safety profile, an agent has what it needs to call and interpret this 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 tool takes zero parameters, so the baseline is 4 and there is nothing to document. The description correctly implies a parameterless call and puts the detail into return-value semantics instead.

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 latest quarterly reading of the American Distress Index (ADI) composite.' The resource is clearly distinct from the sibling indicator tools, though the description never names those siblings or distinguishes itself from get_indicator/get_county_scorecard explicitly.

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

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

Usage is only implied: it is the tool for the ADI composite, and 'Updated quarterly' hints at refresh cadence. There is no explicit 'use this when / use get_indicator instead when' routing, and no guidance on what to do if a quarter hasn't been published.

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 behavior, and the description adds substantial context beyond them: the meaning of the 0-100 score, that national_rank_ordinal is only populated for the top/bottom 100, the five domain breakdown, and citation formats. This is exactly the behavioral detail 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 front-loaded with purpose and packed with useful return-value detail. It is dense rather than bloated, though the closing '3,144 counties available' repeats schema content and the return-field list could be structured more scannably.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: score meaning, rank behavior, domain breakdown, findings, and citations. Combined with annotations covering safety, nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% and the single parameter already documents the 5-digit string format, zero-padding, and county count. The description restates the 4-digit acceptance and availability, adding little beyond the schema, so 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 (Fetch), resource (a county's County Distress Index scorecard), and access key (5-digit FIPS code). It is clearly distinguishable from sibling indicator and composite tools without needing to open 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?

Usage is implied by the precise resource description, but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as get_adi_composite or get_indicator. An agent can infer the use case, but the description does not actively guide 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 already establish a safe read-only, idempotent, closed-world operation. The description goes well beyond them by disclosing the five-filter validation pipeline, the exact return shape (`as_leader` and `as_follower`), and the critical behavioral fact that only fully-validated pairs surface and empty lists are common. With no output schema, this is exactly the context an agent needs.

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

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

The description is front-loaded with purpose, return structure, and the empty-list caveat, and every sentence supports agent decision-making. The enumerated five-filter pipeline is slightly verbose but earns its place by justifying why partial matches are excluded.

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

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

Given a read-only lookup with a fully documented single parameter, no output schema, and no annotations gaps, the description is complete: it explains what is returned, how strict validation is, and what an empty result means. 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 single `slug` parameter is fully documented in the schema. The description reinforces the lookup intent and the empty-list behavior but adds no syntax or format detail beyond what the schema already provides, making the baseline 3 appropriate.

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

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

States a specific verb+resource: fetching statistically-validated leading/lagging relationships for an indicator. The purpose is unambiguous and distinct from sibling lookup tools, but it never explicitly names or contrasts with alternatives like get_indicator or search_indicators.

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

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

Usage is implied by the description ('for an indicator', returns split lists) and the warning that most indicators return empty lists usefully sets expectations. However, there is no explicit when-to-use guidance, no when-not conditions, and no named alternative for related lookups.

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, so the bar is lower; the description adds genuine behavioral context by enumerating the return envelope (latest value, unit, frequency, direction, aggregates, editorial prose, citations) and by calling out the exclusions. It says editorial prose is 'when available', which usefully warns of optional 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?

Front-loaded with the core action and scope, then a dense single enumeration of returns, then the exclusion and slug examples. Three compact sentences with no filler, though the slug examples slightly repeat 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?

With no output schema, the description carries the return-shape burden and does so: it lists every category of returned data, flags optional editorial prose, and points to where the full series lives. Only the unresolved sibling overlap (get_indicator_v2) keeps it from a 5.

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 slug parameter is already fully documented including the 'use search_indicators first' hint and the 121-indicator count. The description's slug examples duplicate the schema rather than adding new semantics, 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?

Names a specific verb ('Fetch') and resource ('American Default economic indicator by slug'), and enumerates exactly what the snapshot contains. However, it never distinguishes itself from the sibling 'get_indicator_v2', which an agent will see in the same list and may confuse it with.

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 scopes the tool to a 'compact snapshot' and states that raw historical series is NOT included, routing that need to the external JSON endpoint. That is a real when/when-not split, but the guidance is against an external URL rather than the sibling tools, leaving get_indicator_v2 and search_indicators unaddressed here.

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, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond those: it says the tool 'fails closed' for unsupported versions and lists the comparison-safety fields `trend_suppressed` and `series_breaks`, which are useful behavioral details not present in 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 two sentences with front-loaded purpose, followed by key return fields, versioning constraint, and a sibling pointer. Every sentence earns its place; no redundancy or fluff.

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 rich annotations and fully documented parameters, the description covers the return fields (`latest value`, `canonical citation`, `trend_suppressed`, `series_breaks`), the versioning requirement, and the legacy alternative. No output schema exists, but the description provides enough detail about the response to be complete.

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 `slug` and `response_version` have clear descriptions in the schema. The description re-emphasizes that `response_version` must be 'v2' and that unsupported versions fail closed, but does not add new semantic meaning beyond what the schema already provides. Thus 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 opens with a specific verb+resource: 'Fetch an explicitly versioned compact indicator snapshot.' It clearly distinguishes this tool from the sibling `get_indicator` by noting the legacy tool remains pinned to its original v1 shape, so this is the v2 counterpart.

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 states the caller must pass `response_version='v2'` and that unsupported versions fail closed, giving a clear when-to-use constraint. It also names the alternative `get_indicator` for the original v1 shape, providing a direct sibling comparison.

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, idempotentHint and non-destructive behavior, so the description focuses on what annotations cannot convey: the substring+prefix ranking over slug/branded_name/name/category, the result set fields, and a worked example of how a query maps to ranked hits. Remaining gaps are edge behavior — zero-match handling, case sensitivity, and ordering ties — none of which are stated.

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

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

Front-loads purpose, then returns, then mechanics, then the routing hint — a sensible order with no filler. The 'e.g. savings' example is informative but occupies a sizable share of the text, making the whole slightly longer than strictly necessary.

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

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

With no output schema, the description carries the burden of describing return values and does so (ranked matches with slug, branded name, underlying name, category, canonical URL). Combined with the scoring explanation and the pointer to get_indicator, an agent has everything needed to call this correctly and use the result.

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

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

Schema description coverage is 100%, so both parameters are already fully documented, including the default 10, cap 50, and clamping. The description restates the default and max limit and the query matching fields, adding no syntax or format detail beyond the schema, 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 ('Search the 121-indicator registry by keyword') and immediately describes what it returns (slug, branded name, underlying name, category, canonical URL). It is clearly distinguishable from get_indicator, which the description names as the follow-up step once a slug is discovered.

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

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

Explicitly says when to use it: 'when you want to discover which slug corresponds to a concept before calling get_indicator' — a clear discover-then-fetch workflow. It lacks any when-not guidance and does not distinguish between the get_indicator and get_indicator_v2 siblings, leaving slight ambiguity about which fetch tool to chain into.

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