American Default Research

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral context beyond annotations by specifying quarterly update frequency and enumerating the exact return components, including the rank in history and domain breakdown. No contradiction with 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, front-loaded with the primary action and resource, and every sentence adds meaningful detail about the return payload and update cadence. No filler or repetition.

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

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

Given zero parameters and no output schema, the description is remarkably complete: it lists the score range, band with label/gloss, historical rank, and all five domains with member component percentiles. It provides sufficient context for an agent to understand what the tool returns.

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

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

The tool has zero parameters, so the baseline score is 4 per the rubric. The description fully discusses the expected result without needing to explain any parameter meanings.

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 uses a specific verb ('Fetch') and named resource ('American Distress Index (ADI) composite') with a clear scope ('latest quarterly reading'). It distinguishes itself from siblings like get_indicator by being specific to the composite and its unique return payload.

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

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

The description implies usage for retrieving the latest ADI composite and its detailed breakdown, but it does not explicitly state when to use this tool over alternatives or list sibling tools for comparison. No exclusions or alternative guidance are provided.

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, and non-destructive behavior. The description adds useful context beyond annotations: input flexibility (4-digit zero-padding), coverage (3,144 counties), and the exact nature of returned data. This is meaningful additional transparency without 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?

Three sentences front-loaded with purpose, then return details, then input quirks and coverage. Every sentence earns its place with no filler or redundancy.

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

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

With no output schema, the description thoroughly enumerates all major return components: composite score, label, ranks, 5-domain breakdown, key findings, and citations. It also addresses input formatting and availability, making it complete for a single-parameter read-only 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 schema description already provides 100% coverage for the single 'fips' parameter, including a detailed example and zero-padding behavior. The description repeats this information but does not add new semantic meaning beyond what the schema states, so the baseline score 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 uses a specific verb ('Fetch') and identifies a unique resource ('County Distress Index (CDI) scorecard') keyed by FIPS code. It distinguishes itself from sibling tools like get_indicator or get_adi_composite by detailing the composite score, domain breakdown, and citations it returns.

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 indicates the tool is for fetching a full county scorecard and specifies input format ('5-digit FIPS', '4-digit FIPS with implicit leading zero'). It does not explicitly state exclusions or alternatives, but the context makes it apparent this is for county-level aggregate data rather than individual indicators.

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

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

Annotations already declare read-only, idempotent, non-destructive hints, and the description adds valuable behavioral details: the multi-stage validation process, the split return structure, and the expectation that most queries yield empty results. This goes well beyond the annotations and prepares the agent for common outcomes.

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, front-loaded with the core purpose, followed by the validation source, and then the return behavior and typical outcome. Every sentence contributes unique information without redundancy.

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

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

With one parameter, good annotations, and no output schema, the description covers the essential context: what the tool does, how results are structured, and the common empty-list case. It provides sufficient information for an agent to invoke it correctly and interpret 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?

The schema provides 100% coverage of the single 'slug' parameter with a detailed description, including examples and expected return format. The tool description reinforces this but adds no new information beyond what the schema already states. 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 clearly states the tool fetches 'statistically-validated leading/lagging relationships for an indicator,' which is a specific verb+resource. It further distinguishes from siblings by naming the five-filter scanner pipeline and explicitly returning 'as_leader' and 'as_follower' lists. This makes the tool's purpose unmistakable.

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 provides clear context on when to use the tool: to obtain validated leading/lagging relationships for a specific indicator. It also implies when not to worry about empty results ('Most ... return empty lists'). However, it doesn't explicitly name alternatives or state when to prefer sibling tools, 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses meaningful behavior: it returns pre-computed aggregates, editorial prose when available, canonical citations, and deliberately omits raw historical series. It also provides an alternative source for the missing data, which is valuable transparency.

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 efficiently structured: a front-loaded sentence states the tool's purpose and return contents, followed by a crucial exclusion/alternative and concrete slug examples. Every sentence adds value, and there is no redundant or filler language.

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 by listing fields (latest value, unit, frequency, direction, aggregates, prose, citations). It also addresses the main limitation (raw series not included) and offers an alternative source, making the tool fully contextualized for an agent.

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 has 100% coverage for the only parameter (slug), including format, examples, and a pointer to search_indicators. The description reinforces the slug examples but does not add new parameter semantics beyond what the schema provides, so the baseline score 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 opens with a specific verb ('Fetch') and a clearly bounded resource ('compact snapshot of an American Default economic indicator by slug'). It enumerates distinct return contents and explicitly contrasts with the raw historical series API, distinguishing itself from alternatives like get_indicator_v2.

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 when-to-use guidance by stating that this tool returns a compact snapshot and that the raw historical series is not included, directing the reader to a direct API URL for full data. It also references search_indicators for slug discovery in the schema description. However, it does not explicitly contrast with sibling get_indicator_v2.

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 readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral details: ranking mechanism (substring+prefix), default limit and max, and the exact fields returned. This goes well beyond the annotation baseline.

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

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

Three sentences, front-loaded with the primary action, followed by return details, scoring explanation, and usage guidance. Every sentence contributes; no filler or repetition.

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

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

For a search tool with no output schema, the description fully covers what is returned, how results are ranked, and how to use the result (get_indicator). Combined with the schema and annotations, this is a complete picture.

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 both parameters are well-documented. The description adds extra semantic value by explaining the scoring fields and the example, which enriches understanding of the query parameter beyond the schema description.

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 searches a specific resource (103-indicator registry) and returns ranked matches. It explicitly differentiates from the sibling get_indicator by framing this as the discovery step before fetching a specific indicator.

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 explicit usage context: 'Use this when you want to discover which slug corresponds to a concept before calling get_indicator.' This tells the agent exactly when to choose this tool over the sibling, and the example clarifies what kind of queries work.

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