LiveDataLink

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

Annotations already establish this as read-only, idempotent, open-world, and non-destructive. The description adds behavioral detail by stating the response includes a health category rating and specific pollutant levels, which helps the agent set expectations about live, current measurements.

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

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

The description is front-loaded with the tool's purpose and return data, then gives a practical set of example queries. The list of query phrasings is slightly redundant near the end, but overall it is crisp and useful.

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-parameter read-only tool with strong annotations and a complete schema, the description covers what data is returned and the kinds of questions it answers. It does not discuss data freshness, units, or coverage limitations, but these are minor gaps given the tool's simplicity.

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 fully documents the single 'location' parameter as 'City, zip code, or place name' with 100% coverage. The description's examples reinforce that location can be a place name like Los Angeles, but it does not add meaning beyond the schema, 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 uses a specific verb ('Get'), a clear resource ('current air quality data'), and enumerates the exact data returned (US AQI, PM2.5, PM10, ozone, NO2, SO2, CO, health category). It is immediately distinguishable from weather, health, or pollution-related sibling tools.

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 explicit natural-language triggers ('what's the air quality?', 'is it safe to go outside?', 'AQI in Los Angeles') and states to use it for 'any air quality or pollution question.' It does not name alternatives or exclusion cases, but the guidance is clear enough for an agent to select this tool confidently.

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?

With readOnly/idempotent annotations already covering safety, the description adds behavioral nuance beyond structured data: 'FDIC is the primary signal; CFPB complaint data is best-effort and degrades gracefully if the bank's complaint records cannot be matched,' plus the explicit 'not a rating or advice' boundary.

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 and front-loaded with the core purpose, and each sentence pulls weight (data sources, output, fallback, use cases). It loses a point for restating parameter guidance already present in the schema, making it slightly longer than 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 still communicates the returned read's contents: the category label, underlying financial metrics, complaint volume/products, and graceful degradation. The use-case and disclaimer sentences close the remaining selection and invocation questions.

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 schema already documents both params and the full-legal-name matching tip. The description's 'bank name or FDIC certificate (CERT) number' reinforces the one-of relationship but adds little beyond what the schema states.

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 action ('financial-health read'), a specific resource ('US bank or savings institution'), and concrete output categories (HEALTHY/STABLE/WATCH/FAILED). The explicit FDIC + CFPB join distinguishes it from sibling FDIC-only and CFPB-only tools.

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 concrete use cases (sponsor/partner bank selection, treasury counterparty checks, deposit-safety questions) and frames the tool as a one-call read, which implies when it is appropriate. However, it never names alternatives or says when-not-to-use it, so the guidance is clear but not fully exclusionary.

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/openWorld/idempotent annotations: it discloses the GLEIF mapping approach, the ~15 entity cap, the sanctions sources screened, best-effort failure behavior, that only self-reported GLEIF relationships are shown, and that name matches are not proof of identity. 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?

Though long, the description is dense with non-redundant information and every sentence earns its place: purpose, method, scope, failure behavior, return contents, and caveats. The core value proposition is front-loaded in the first sentence.

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

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

With no output schema, the description still explains what the tool returns: mapped ownership structure, per-entity CLEAR/HIT results with matched list entry/source/score, and an overall verdict. It also covers edge cases like GLEIF failure and unavailable sanctions binding, making it practically complete 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?

Schema description coverage is 100%, so the schema documents both parameters. The description adds meaningful semantics on top: the LEI must be 20 characters, an LEI can be supplied via either field, and the lei parameter overrides a name search. This helps the agent disambiguate parameter usage.

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: a one-call KYB/AML ownership-chain sanctions screen. It clearly frames the real question being answered and distinguishes itself from a simple top-level-name list check, which separates it from related screening and lookup tools.

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 explains when this tool is valuable: when ownership-chain exposure must be caught beyond screening only the counterparty name. It references the same matcher as company_trust_check and notes GLEIF-based mapping, giving useful context, though it does not explicitly enumerate sibling alternatives or state hard 'do not use when' conditions.

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 read-only, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations: no API key is needed and the result is a monthly time series. It does not mention possible data revisions or lags, but the annotation-covered safety profile lowers the burden and the added details are meaningful.

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 focused sentences: a scoped subject, a concise indicator list, and a useful return/auth note. Every sentence earns its place and the most important identifying 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?

For a simple read-only tool with three optional parameters and no output schema, the description conveys the domain, supported indicators, monthly frequency, and keyless access. It could specify the exact time-series shape or units, but it is sufficient for an agent to select and invoke 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?

Schema description coverage is 100%, with all three parameters already documented including defaults and the full indicator enumeration. The description restates the indicator list but adds no extra semantics such as date formats, units, or interactions between start_year and end_year.

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 data source (Bureau of Labor Statistics), the domain (US labor and price statistics), and the supported friendly-name indicators. It lacks an explicit action verb like 'get' or 'fetch' and does not explicitly distinguish itself from the sibling bls_series tool, so it falls just short of full 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?

There is no explicit guidance about when to use this tool versus alternatives like bls_series or FRED tools. The phrase 'by friendly name' and the indicator list imply the use case, but the description never states when not to use it or what to use instead for raw BLS series or different datasets.

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 idempotentHint, and the description's 'Fetch' aligns as a safe read operation. The description adds no behavioral caveats such as output format, rate limits, or year-range constraints, so it only mildly extends what annotations already 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?

Two sentences with the action and example front-loaded, followed by the exact-ID selection criterion. No filler, fluff, or redundant restatement of schema fields.

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 fetch with one required parameter and clearly documented optional years, selection and invocation are well covered. With no output schema, the response shape is left unstated, but the description still provides enough for correct tool usage.

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 series_id, start_year, and end_year already described. The description repeats an example ID also found in the schema and does not clarify year range behavior, so it meets the baseline without adding meaningful parameter insight.

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 'Fetch any BLS time series by its raw series ID', which is a specific verb, resource, and exact input. The examples and the 'when you know the exact BLS series ID' clause distinguish it from lookup or search siblings.

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

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

It explicitly identifies the right condition: use when the exact BLS series ID is known. It does not name sibling alternatives or provide a when-not, so exclusions are left implicit.

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 that the tool is read-only, idempotent, and non-destructive. The description adds value by disclosing the concrete return fields, including the notable 'whether its full text is indexed here' behavior, which is not inferable from the input schema. It does not cover not-found or error behavior, but the annotation coverage lowers that burden.

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 a single front-loaded sentence with the field list in a parenthetical. There is no filler, no repetition of schema details, and every phrase contributes to understanding what the tool returns.

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 simple single-parameter lookup with strong annotations, the description is complete: it identifies the required input and the full set of returned metadata fields. Since there is no output schema, the description appropriately carries the return-value information needed by the 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 input schema already documents gutenberg_id with 100% coverage and a concrete example ('84 (Frankenstein)'). The description only restates that the parameter is a Project Gutenberg id and adds no additional syntax or format details, 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 states a specific verb and resource: 'Get full catalog metadata for a single book by its Project Gutenberg id.' It enumerates the exact metadata fields, making it clearly distinguishable from sibling tools like book_search, book_get_text, and book_fulltext_search.

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 makes the usage context clear: use this when you already have a Gutenberg id and need catalog metadata for one book. It does not explicitly name alternatives or exclusions, but the 'single book by id' framing is sufficient to differentiate it from search and text-retrieval 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 establish read-only, idempotent, non-destructive behavior. The description adds useful context beyond annotations: the corpus is indexed public-domain books, results include title/author/snippet, and search can be narrowed to one book. 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?

Three sentences with the action verb front-loaded ('Search INSIDE...'). The phrase 'headline feature' adds minor positioning context, but every sentence otherwise earns its place 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 no output schema, the description covers the return shape (matching passages with title, author, snippet) and the scope of the corpus. It does not mention no-results behavior or pagination, but limit defaults are documented in the schema and the overall behavior is clear.

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 each parameter already has a clear description, including examples for query. The description only restates the gutenberg_id restriction role and adds little semantic value beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Search INSIDE the indexed corpus of top public-domain books') and the exact output ('matching passages, each with the book title, author, and a snippet'). It clearly distinguishes itself from siblings like book_search and book_get_text by emphasizing passage-level full-text search.

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 makes the use case explicit: find where a passage or phrase appears across books, with optional restriction to a single book via gutenberg_id. It does not name alternative sibling tools or state when not to use it, but the context is clear enough for an agent to select appropriately.

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 idempotent. The description adds meaningful behavioral context beyond those annotations: results are paginated by passage, and non-indexed books return a gutenberg.org URL instead of text, which is an important non-obvious fallback behavior.

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

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

Three concise sentences: the first states the core operation, the second gives the pagination pattern, and the third covers the fallback case. No filler or repetition of schema details.

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?

Without an output schema, the description still explains both return modes: paginated text passages for indexed books and a plain-text URL for non-indexed books. It is sufficient for correct invocation, though a bit more detail about what constitutes a 'passage' would make it fully self-contained.

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 all three parameters at 100% coverage, so baseline is 3. The description adds value by explaining the pagination relationship between from_seq and max_passages and by tying gutenberg_id to the indexed-versus-URL fallback behavior, which the schema alone does not convey.

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 and resource: 'Return the full text of an indexed book by Gutenberg id'. It also clarifies the pagination model and the fallback behavior for non-indexed books, which distinguishes it from search-oriented siblings like book_fulltext_search and book_details.

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 direct usage guidance: 'Use from_seq + max_passages to page through it' and explains the alternate path for unindexed books by returning a URL. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is clear for this retrieval action.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description adds useful behavioral context beyond them: live Gutendex source, ranking by keyword relevance then download popularity, and the exact fields returned. This gives the agent a strong sense of what the tool will do and what to expect.

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 dense sentences with no filler. The core search scope and filters come first, followed by ranking behavior, return fields, and the sibling-tool routing at the end. 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?

There is no output schema, so the description compensates by listing the returned fields. It also explains scope, source, ranking behavior, and the relevant alternative tool. For a search tool with optional filters and safety annotations, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with each parameter already documented with examples and defaults. The description mostly restates that query accepts title/author/subject keywords and that author, subject, and language are optional filters, without adding significant new parameter-level meaning beyond the schema.

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

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

The description states a specific action ('Search the full Project Gutenberg catalog') with a clear resource, scope, and method (Gutendex). It explicitly distinguishes itself from book_fulltext_search by naming that sibling and clarifying the different search domain (metadata vs full text).

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 explicitly tells the agent to use book_fulltext_search when the task is to search inside book text, providing a clear routing rule. It also characterizes book_search as a live catalog search, so an agent can infer when this tool is appropriate versus sibling tools.

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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations by clarifying that the catalog is served live via Gutendex and that the D1 counts are local indexed-corpus statistics, including the last refresh timestamp. This helps the agent understand what data source and freshness semantics to expect.

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 a single, well-structured sentence that front-loads the core purpose ('Report the books store status') before listing the key data components. Every element adds value: data source, scale, indexed-corpus metrics, and refresh timestamp. There is no filler or redundant restatement of the tool name.

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 status-reporting tool, the description is complete. It tells the agent what to expect in the response: live catalog availability, indexed corpus counts, total passages, and last refresh timestamp. No output schema is present, but the description compensates well by outlining the return categories. No additional context seems necessary 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?

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description appropriately focuses on the output content instead. Because there is no input schema burden, the description does not need to compensate for undocumented parameters.

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 ('Report') and a clear resource ('books store status'), then enumerates exactly what the status contains: live Gutendex catalog, local D1 indexed-corpus counts, and last refresh timestamp. This clearly distinguishes it from sibling book tools like book_search, book_details, and book_fulltext_search, which operate on individual books or search results rather than the store's health.

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 this is the tool to use when an agent needs a high-level status or health summary of the books store, rather than specific book content. However, there is no explicit when-to-use guidance, no mention of when not to use it, and no reference to alternative sibling tools. The usage intent is clear enough but left implicit.

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, so the safety profile is covered. The description adds valuable behavioral context beyond that: it is a heuristic research signal, not investment advice; all thresholds are tunable parameters; and the per-symbol return fields are enumerated. No contradiction with annotations 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 three sentences with zero filler: strategy conditions, output format, tunability, and disclaimer all fit naturally. The core action is front-loaded, and every sentence carries distinctive information. This is appropriately dense rather than bloated.

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 there is no output schema, the description lists the exact return fields and explains the strategy criteria, threshold tunability, and heuristic nature. All six parameters are documented in the input schema, and the intended ticker scope (US, daily bars) is explicit. An agent has enough information to select and invoke this 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?

Schema description coverage is 100%, so the baseline is 3 because the schema already documents each parameter. The description adds extra meaning by explicitly labeling rsi_threshold, ma_period, proximity_pct, and lookback_days as tunable thresholds and explaining that calibration is achieved through parameter changes. This links the parameters directly to the strategy logic beyond what the schema states.

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 action ('Screen one or more US tickers') and a clearly defined resource/strategy: a mean-reversion 'bounce' setup with explicit conditions (near support/MA, RSI oversold and turning up, bullish latest candle, volume at/above average). It also specifies the exact output shape, which leaves no ambiguity about what the tool does. The definition is distinctive enough to be separated from siblings like candlestick_signals or support_resistance_levels without reading their schemas.

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 for when to use the tool: when screening US tickers for daily-bar mean-reversion bounce setups. It does not explicitly name alternative tools or state when not to use it, but the strategy-specific wording makes the intended use obvious. It stops short of a 5 because no explicit 'use X instead when...' guidance is 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 cover the read-only, idempotent, non-destructive nature, lowering the bar. The description adds important behavioral context by flagging HEURISTIC detection with conservative default thresholds and stating the tool is for research, not investment advice. This helps the agent temper expectations about precision.

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 tightly written sentences: the first delivers the core action, pattern list, and return shape; the second adds a necessary heuristic caveat. No filler, and the most important identifying 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?

With no output schema, the description's explicit return-field list ({pattern, date, direction, barIndex}) is valuable. It covers the essentials for a simple read-only scanner, though it could mention edge cases or the meaning of barIndex more explicitly. Overall, it is sufficiently complete for the tool's complexity.

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 symbol and lookback_days. The description does not add substantial parameter-level detail beyond reaffirming the daily-bar scope, 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 states a specific action ('Detect'), a specific resource ('classic candlestick patterns on a ticker's recent daily bars'), and enumerates the exact patterns covered. It also specifies the return fields, making the tool's purpose unambiguous and clearly distinct from siblings like stock_history or support_resistance_levels.

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 context (recent daily bars, research-oriented) and adds a 'not investment advice' caveat, but it does not explicitly say when to prefer this tool over similar technical-analysis siblings like support_resistance_levels or bounce_scanner. No alternatives or exclusions are named.

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 convey read-only, idempotent, and non-destructive behavior. The description adds 'Keyless' to clarify that no authentication is required, which is valuable operational context. It also lists the response content, partially compensating for the absence of an output schema.

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 short sentences with no wasted words. The lookup target and returned fields are front-loaded, and the 'Keyless' note is a concise, useful addition.

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 simple one-parameter, read-only lookup with no output schema, this description is complete: it identifies the source platform, the input semantics, the returned fields, and the authentication requirement. Nothing critical is missing for an agent to invoke it correctly.

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

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

The input schema already documents the single 'name' parameter with an example. Schema description coverage is 100%, so the baseline is 3. The description adds context by specifying 'Rust crate' and 'crates.io', but it does not materially deepen parameter semantics beyond the schema.

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

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

The description uses a specific verb and resource: 'Look up a Rust crate on crates.io', which clearly distinguishes it from sibling package lookup tools like npm_package and pypi_package. It also enumerates the exact returned fields, so an agent knows what this tool 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?

The description clearly establishes the context for use: any time a Rust crate's metadata from crates.io is needed. It does not explicitly name alternatives or exclusions, but the platform and language are explicit enough to guide selection among package-oriented siblings.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's job is to add context beyond that. It does so by disclosing the important behavioral trait that LiveDataLink does not silently retain customer watchlists, plus the compare fields and return shape. No contradiction with annotations; 'recheck' is consistent with a non-destructive, idempotent read operation.

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 every sentence earns its place: purpose, inputs, comparison fields, return values, and the storage/scheduling caveat. It is front-loaded with the core purpose and organized logically, though it could be tightened slightly without losing 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?

With five parameters and no output schema, the description compensates by specifying exactly what the tool returns (unchanged/changed status, severity, field-level changes, next reviewer action). It also covers the operational requirement for the agent to store snapshots. Minor gaps like error handling or refresh timing are not critical for a read-only recheck tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds modest value by emphasizing that previous_snapshot is the prior result or snapshot required for comparison and that DOT/MC/name are identifiers, but it does not substantially enrich the parameter semantics beyond the schema.

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

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

The description uses a specific verb ('Recheck') with a specific resource ('existing carrier snapshot') and states the precise goal: identify meaningful changes since the previous check. It clearly lists what is compared and what is returned, making it readily distinguishable from sibling tools like carrier_vetting_batch or fmcsa_carrier_lookup, which perform initial checks or lookups rather than repeat comparisons.

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 operational context: store the returned current_snapshot yourself, call the tool on a schedule, and rely on it to detect changes over time. It stops short of naming alternatives or stating when not to use it, but the intended usage pattern is clear and actionable.

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 adds substantial behavioral detail beyond the readOnly/idempotent annotations: each carrier consumes one plan query, carriers are evaluated independently, missing records do not hide others, and outputs include source coverage and failures. It also includes the important caveat that this is 'an analytical aid, not a substitute for direct FMCSA verification.'

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 tightly written with no filler. It front-loads the core action and scope, then covers outputs, usage, plan cost, resilience, and limitations in three efficient sentences. Every sentence contributes to agent decision-making.

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 there is no output schema, the description compensates by listing what is returned (status per carrier, source coverage, failures, authority/insurance/safety signals, export formats). It also covers usage context, plan cost, and reliability behavior, making it complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reinforces the 1-10 batch limit and the convenience of comma-separated strings, but adds little semantic meaning beyond the schema. This meets the baseline for high schema coverage.

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 specific verb ('Vet'), resource ('US motor carriers by USDOT number'), and scope ('up to 10... in one workflow call'). It also describes the key output (GO/CAUTION/NO-GO per carrier), making its purpose distinct from single-carrier siblings like carrier_vetting_score.

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

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

The description explicitly tells when to use the tool: 'Use this to screen a broker's candidate list or lane roster.' It notes the batch behavior and resilience to missing records. It does not explicitly name sibling alternatives or when not to use it, but the context is clear.

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

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive, and the description adds behavioral nuance beyond them: the versioned receipt fingerprint only 'helps detect accidental changes after export' and is explicitly not tamper-proof or a certification. It also discloses that the pack reports 'source coverage and failures', signaling that results may be incomplete, which aligns with openWorldHint.

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 dense sentences, each earning its place: output list, receipt caveat, sibling routing, and compliance disclaimer, with the purpose front-loaded. The enumerative middle sentence is long, but it compensates for the absent 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?

With no output schema, the description carries the burden of explaining return content, and it fully enumerates the verdict, FMCSA evidence, sanctions/court/award checks, source coverage and failures, timestamp, links, fingerprint, and follow-up checklist. Input resolution options and limitations are also covered, so 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%: mc, dot, and name each carry format examples, and dot is marked preferred. The description adds only that resolution proceeds 'by USDOT, MC, or legal name', which restates the schema; with full coverage, 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 opens with a specific verb and resource — 'Produce an auditable Carrier Vetting Pack for a freight broker' — and enumerates the exact verdict and evidence contents. It explicitly differentiates from the sibling carrier_vetting_score by calling itself the 'evidence-first companion' for saving or forwarding the record, so an agent can tell them apart without opening either 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 names the alternative carrier_vetting_score and gives the selection condition: use this tool when a human reviewer needs to save or forward the record. It also states the when-not cases — 'not tamper-proof storage or a compliance certification' and 'not a substitute for direct FMCSA insurance and authority verification' — leaving nothing to inference.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the data sources joined, the decision categories, and the precise triggers for NO-GO and CAUTION. It also correctly labels the output as an analytical aid rather than a substitute for onboarding checks, which is meaningful behavioral context.

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 every sentence adds essential information: purpose, input options, data sources, output semantics, decision thresholds, and a caveat. It remains front-loaded and structured, with 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?

With no output schema present, the description fully compensates by explaining the return value (GO/CAUTION/NO-GO with reasons and underlying fields) and the conditions that lead to each result. It also covers inputs, data sources, and limitations, so an agent has enough 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?

Schema description coverage is 100%, so the input schema already documents all three parameters including accepted formats and the name-match caveat. The description adds a brief restatement of the three input options but no significant new parameter meaning beyond the schema.

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

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

The description opens with a precise verb ('Vet'), a specific resource ('US motor carrier... for a freight-brokerage review'), and the 'in one call' qualifier that separates it from batch or evidence-pack siblings. It also names the decision output (GO/CAUTION/NO-GO), making 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?

It clearly states the intended context: vetting a US motor carrier for a freight-brokerage review, with DOT/MC/name as alternative entry points. It does not explicitly say when to prefer this over carrier_vetting_batch, carrier_vetting_evidence_pack, or fmcsa-specific lookup tools, but the context is clear enough to place it.

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 that this is read-only, idempotent, non-destructive, and open-world. The description adds behavioral clarity by specifying the exact payload fields (name, citations, court, jurisdiction, decision date, reporter location, source URL) and indicating that the full text itself is not returned. No contradiction exists between description and 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?

A single front-loaded sentence gets straight to the action and resource, with the field list in parentheses. There is no filler or repetition; every clause 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?

For a one-parameter, read-only, idempotent lookup with no output schema, the description is complete: it identifies the input and enumerates the expected return fields. An agent can select and invoke the tool correctly without additional context.

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

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

With 100% schema coverage for the single required id parameter, the baseline is 3. The description merely repeats that the lookup is by CAP id and adds no extra format, range, or semantics beyond the schema's example and type.

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 action and resource: 'Get full metadata for a single case by its CAP id.' It enumerates the exact metadata fields returned and clarifies that the full text is only referenced by URL, which distinguishes it from sibling tools like caselaw_opinion_text, caselaw_search, and caselaw_citation_lookup.

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 'single case by its CAP id' gives a clear context for use: an agent should call this when it already has a CAP id and needs the case metadata record. The mention of the source URL for full text implicitly signals that full-opinion retrieval is out of scope, though no sibling tool is explicitly named and no when-not-to-use guidance is 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 establish read-only, idempotent, and non-destructive behavior, so the description only needs to add value beyond that. It adds useful behavioral detail: it matches official and parallel citations, tolerates citation variants like '347 U. S. 483', and returns metadata including the CAP id. 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?

Two sentences carry the full necessary meaning: purpose, input examples, matching behavior, output, and downstream use. There is no filler, and the core action 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?

For a one-parameter, read-only lookup with no output schema, the description is complete: it says what input is expected, what matching behavior occurs, what the return value contains, and how the result connects to caselaw_opinion_text. Nothing essential for correct invocation 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 schema already documents the single citation parameter with an example, and coverage is 100%. The description enriches the parameter meaning by providing additional format examples and explicitly stating that official and parallel citations are matched, which helps the agent understand acceptable inputs.

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: 'Resolve a reporter citation ... to the case it identifies.' It also clarifies that it matches official and parallel citations and returns metadata with a CAP id. It does not explicitly distinguish itself from similar siblings like court_citation_resolver or caselaw_search, though the downstream link to caselaw_opinion_text helps.

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 implies the intended use case: when an agent has a reporter citation and needs the case identity and CAP id for further caselaw operations. It names the downstream sibling caselaw_opinion_text but does not state when-not-to-use alternatives such as caselaw_search, 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 declare readOnly, idempotent, non-destructive behavior. The description adds useful context beyond that: text is 'retrieved live from the public-domain CAP static mirror (not stored)' and includes each opinion type with its author, which helps the agent understand what will happen when invoked.

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 compact and well-structured: the core action is front-loaded, followed by data-source behavior, output composition, and a parameter-bound usage note. 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?

For a two-parameter read-only tool with rich annotations, this is largely complete: it identifies the input, source, output content, and response bounding. Minor ambiguity remains about the exact return format or behavior when max_chars is exceeded, but no output schema exists to fill that gap.

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 id and max_chars are already documented structurally. The description adds only that max_chars bounds the response and that the id is a CAP case id, which does not significantly extend the schema's own parameter documentation.

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 action ('Fetch the full opinion text of a case') and the required identifier ('by its CAP id'), making the core purpose clear. It does not explicitly differentiate from siblings like caselaw_case_details or caselaw_search, though 'full opinion text' and 'CAP id' imply a distinct retrieval role.

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 when to use the tool ('on demand by its CAP id' and 'Use max_chars to bound the response'), but it does not explicitly state alternatives or when not to use it. The schema's id description points to caselaw_search/caselaw_citation_lookup as sources, but the description itself offers only implied usage context.

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 readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful context beyond those: the data is public domain, results include CAP ids and citations, and the v1 index only covers the U.S. Reports reporter. This is valuable behavioral transparency and does not contradict 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 no filler: purpose first, then output and next-step guidance, then a critical scope caveat. It is front-loaded and every sentence contributes useful 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?

The description covers what is searched, what is returned, how to retrieve full opinions, and a major index limitation. The schema handles parameter details. It stops slightly short of stating whether at least one search criterion is expected or describing the exact result envelope, but for a search tool with strong annotations this is a minor gap.

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%, with each parameter already described and exemplified. The description adds a useful high-level grouping of filters and the decision-date range concept, but does not need to compensate for missing schema documentation.

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 action and resource: searching US court opinions from the Caselaw Access Project by case name, keyword, court, jurisdiction, and date range. It clearly differentiates itself from the sibling caselaw_opinion_text by describing its metadata output and directing the agent to that sibling for full opinion text.

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 an explicit follow-up/alternative: 'Use caselaw_opinion_text with a returned id to read the full opinion.' It also sets expectation with the v1 U.S. Reports coverage note. However, it does not explain when to prefer other sibling search tools such as caselaw_citation_lookup or court_opinion_search.

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, so the safety profile is covered. The description adds context that this is an arbitrary SoQL query against any CDC dataset, but does not mention response shape, pagination, or rate-limit behavior. With annotations carrying the safety burden, this is adequate but not exemplary.

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 with no wasted words: the generic scope, the usage rule, and the required input format. The SoQL reference link is useful and placed at the end without disrupting the core guidance.

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 rich schema coverage, strong annotations, and the inherently flexible nature of a generic query tool, the description is largely complete. The SoQL reference helps fill the gap left by no output schema, though it does not describe expected return format or mention how to discover valid dataset IDs.

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 fully documents all five parameters. The description reinforces that dataset is a 4x4 Socrata ID and mentions where-clause support, but adds no meaning beyond the schema's parameter descriptions. 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 and resource: 'Generic SoQL query against any data.cdc.gov dataset.' It also distinguishes itself from siblings by positioning itself as the fallback when 'none of the curated tools fit,' making its role in the tool hierarchy clear.

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 explicitly says to use it when none of the curated tools fit, which is clear contextual guidance. It does not enumerate specific alternative tools or spell out when not to use it, but the generic-vs-curated distinction is enough for an agent to route correctly.

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 communicate readOnly, idempotent, and non-destructive behavior. The description adds useful context with '12-month rolling counts' and the dataset ID, which goes beyond the annotations. It does not mention response format, temporal coverage, or pagination behavior, so it adds some but not rich behavioral detail.

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 short sentences, and each one earns its place: identifying the dataset, describing the rolling-count aggregation, and stating practical use cases. There is no filler, redundancy, 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?

For a read-only tool with three optional parameters and no required inputs, the description covers the subject, dimensions, aggregation, and intended applications. It is missing explicit details like date range or row contents, but given the simple schema and strong annotations, it is adequately 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%, so the schema already documents all three parameters: limit, indicator, and state_name. The description merely restates 'by state and indicator' without adding new parameter-level meaning. This matches the baseline where the schema does the heavy lifting.

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

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

The description clearly identifies the resource as 'CDC drug overdose deaths by state and indicator' and adds the dataset ID (9j2v-jamp), making it distinct from related CDC tools. It lacks an explicit verb like 'returns' or 'provides', but the intent is unmistakable. It differentiates well from siblings such as cdc_weekly_deaths_by_state and cdc_leading_causes_of_death.

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 use cases ('opioid/fentanyl/stimulant policy research and treatment-program siting'), which imply when this tool is relevant. However, it does not explicitly state when to use this tool versus sibling CDC tools or mention any exclusions. The guidance is implied rather than direct.

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 that the tool is read-only, idempotent, and non-destructive, so the safety burden is covered. The description adds useful context about the data being modeled expected vs observed values, but it does not disclose operational details such as update cadence, response shape, or query limitations. This is adequate but not rich behavioral disclosure.

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

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

Three short sentences each earn their place: the dataset identifier, the data model and granularity, and the intended analytical purpose. There is no filler, repetition of schema content, or unnecessary detail. The key 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?

For a low-complexity, read-only tool with fully documented parameters and safety annotations, the description is sufficient for an agent to understand what the tool returns and why it exists. It does not describe output columns or response formatting, but no output schema is provided and the dataset semantics are clear enough 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 description coverage is 100%, so the schema already documents limit, state, and outcome with examples. The description adds the conceptual framing of 'by state and week' but gives no parameter-specific guidance beyond that. The baseline of 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 clearly identifies a specific CDC dataset (xkkf-xrst) and explains that it contains modeled expected vs observed deaths by state and week. This distinguishes it from siblings like cdc_weekly_deaths_by_state, which would provide observed death data, and cdc_drug_overdose_deaths. Though no explicit verb like 'get' or 'query' appears, the resource and its content are 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 states a clear purpose: estimating true pandemic impact beyond reported COVID deaths. This gives an agent enough context to select this tool over related CDC mortality datasets. It does not explicitly name alternative tools or state when not to use it, but the intended use case is concrete rather than merely implied.

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

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

Annotations already cover safety (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's burden is reduced. It adds useful context about scope (state-level, weekly) and the dataset, but does not describe output format, pagination, or behavior with empty filters. 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 a single sentence that front-loads the source and the return value, with no filler and no repetition of schema fields. The dataset ID is useful and unobtrusive.

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 simple read-only tool with zero required parameters and full schema coverage, the description is nearly complete. It states what is returned and at what granularity. However, since there is no output schema, it could be slightly clearer about the form of 'activity levels' (e.g., categorical vs. numeric) and default behavior when no filters are supplied.

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 describes all three parameters at 100% coverage (limit, season, statename). The description does not add meaningful parameter-level detail 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 names a specific source and resource ('CDC FluView state-level influenza surveillance') and states a clear action with output ('Returns weekly ILI activity levels per state'). It distinguishes itself from sibling CDC tools by focusing specifically on influenza-like illness, and the dataset ID (vh55-3he6) adds precision.

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 when this tool is relevant: any query about state-level flu/ILI activity. However, it does not explicitly state when to prefer this over siblings such as cdc_dataset_query or cdc_weekly_deaths_by_state, nor does it provide exclusions or alternative 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 establish read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful output-shape context but does not disclose potential operational behaviors such as default scope when filters are omitted, available year range, or valid cause-name list. No contradiction with 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?

Two sentences are front-loaded with the dataset source and return values, and the closing use-case sentence adds context without clutter. The dataset ID in parentheses is a minor but useful identifier, not wasted space.

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 simple optional-filter retrieval tool with no output schema, the description provides the key missing output semantics: rows contain deaths and age-adjusted rates by cause, state, and year. It could add valid cause-name/date-range details, but the 100%-covered schema and read-only annotations make the tool safely invokable with reasonable defaults.

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 describes all four parameters at 100% coverage, so the baseline is 3. The description adds value by explaining that results are organized 'per cause per state per year,' clarifying how the optional filters combine into output rows. This goes slightly beyond the one-line schema descriptions.

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

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

The description names a specific resource — the NCHS leading-causes-of-death dataset (bi63-dtpu) — and states the exact returned metrics: total deaths and age-adjusted death rates by cause, state, and year. This makes it easy to distinguish from CDC siblings such as cdc_drug_overdose_deaths or cdc_weekly_deaths_by_state.

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 offers an implied use case ('useful for chronic disease + injury mortality research') but no explicit when-to-use/when-not-to-use guidance or alternative tool suggestions. Among many CDC siblings, the agent is not told why this tool should be selected over cdc_dataset_query or the other CDC dataset tools.

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 read-only, idempotent, non-destructive behavior. The description adds value by enumerating the returned data fields (date, state, etiology, illnesses, hospitalizations, deaths, exposure), which is especially helpful in the absence of an output schema. It does not disclose pagination or default-limit behavior, but the annotations cover the safety profile.

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

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

A single, front-loaded sentence identifies the dataset, scope, and return fields with zero filler. Every word contributes to the agent's ability to understand and invoke the tool.

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 query tool with four optional parameters and no output schema, the description plus schema covers the essential invocation details: dataset, filters, returned fields, and default limit. It stops short of explaining filtering behavior or result-set expectations, but the tool is simple enough that these are minor 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?

Schema coverage is 100%, with each parameter (year, limit, state, etiology) already having a description in the input schema. The tool description names some of these concepts (state, etiology) but does not add meaning 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 names a specific resource (CDC NORS foodborne/waterborne/enteric outbreak reports), the dataset identifier (iezt-77pi), and the exact fields returned. This clearly distinguishes the tool from the many other cdc_* siblings by domain and dataset.

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 intended use is implied by 'CDC NORS ... outbreak reports' and the returned fields, but the description does not explicitly state when to choose this tool over alternatives like cdc_dataset_query or other CDC health datasets. No exclusions or alternative routing 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context: the specific Socrata dataset ID (8xkx-amqh), the breakdown of returned metrics, and the time-series nature. However, it does not disclose default scope when no state/county filter is applied or the time window returned, and no contradiction exists 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?

Three compact clauses front-load the subject, then state the output composition and a use case. Every sentence earns its place; the dataset ID is slightly esoteric but useful for provenance when cross-referencing with cdc_dataset_query.

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 query tool with all-optional parameters and no output schema, the description covers what is returned. But it leaves gaps: what happens with zero filters (all counties? national aggregate?), what date range is covered, and how 'over time' is represented in the response. These are material for an agent invoking it correctly.

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

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

Schema description coverage is 100% — limit, recip_state, and recip_county are all documented in the input schema. The description only hints at county-level granularity ('by US county') and adds no parameter semantics 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?

Description states a clear verb+resource: returns COVID-19 vaccination coverage by US county, with explicit output content (booster + primary series percentages over time). This distinguishes it from sibling CDC tools covering flu, overdose deaths, and other indicators, though it doesn't explicitly differentiate from the generic cdc_dataset_query which could query the same dataset.

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?

'Useful for public-health gap analysis' implies a use case, but there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives. Among many cdc_* siblings, an agent gets no routing help beyond the narrow subject matter.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond those: the 'provisional' nature of the data, the NCHS dataset identifier, and the ISO-week granularity. This meaningfully informs the agent about data freshness and structure 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?

Two sentences deliver the dataset source, output semantics, granularity, and intended use cases with no filler. Key information is front-loaded and 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?

For a simple read-only tool with all parameters documented in the schema and no required parameters, the description is complete enough for safe invocation. It explains what the tool returns, from which dataset, and what analysis it supports, which compensates for the absence of an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description hints at cause categories and state/time granularity, but it does not add much beyond what the schema already documents for year, cause, limit, and state.

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: 'Returns all-cause and selected-cause death counts per state per ISO week' from the CDC NCHS dataset. It identifies the exact dataset id (muzy-jte6) and scope, which clearly distinguishes it from sibling CDC tools like cdc_flu_surveillance or cdc_leading_causes_of_death.

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 for appropriate use: 'excess-mortality and respiratory-disease seasonality analysis.' It does not explicitly name sibling tools to avoid or state when-not-to-use conditions, 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 convey read-only, idempotent, non-destructive behavior, lowering the bar for disclosure. The description adds context about the data source and optional NAICS filtering, but does not describe output format, pagination, or geographic parameter dependencies. No contradiction with annotations 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 two sentences with no filler. The first sentence front-loads the core data content and source; the second efficiently explains the optional filter and use cases. Every clause contributes to selection and invocation understanding.

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 9-parameter tool with no output schema, the description is somewhat thin: it names the data metrics and domain but does not explain geography-level selection rules, return structure, or units. The schema covers required parameter dependencies, but the overall package relies heavily on the schema to make the tool usable. Description is adequate but not comprehensive.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by clarifying that NAICS is an industry filter and that the returned metrics are establishments, employment, and payroll, which helps agents interpret the year and level parameters in context. It does not fully compensate for missing schema-level nuances, but it goes beyond simple duplication.

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: business establishments, employment, and annual payroll from County Business Patterns, with an optional NAICS filter. This differentiates it from sibling census tools like census_demographics or census_population, though it lacks a direct verb such as 'get' or 'query' and does not explicitly name a sibling alternative.

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 useful usage context ('Used for industry research, competitive intel, supply chain analysis') but gives no explicit when-to-use vs. alternative guidance, such as 'for demographic data use census_demographics.' The intended use is implied by the data domain rather than clearly contrasted with sibling tools.

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, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds limited behavioral context beyond that, mostly restating topic areas rather than disclosing output shape, limitations, or data-source nuances.

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 concise sentences front-load the tool's substance with a list of returned data categories, then add use-case context. There is no filler, redundancy, or repetition of the tool name.

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 rich schema descriptions and annotations, the description covers the essential 'what' and 'when' well. It also lists the return subjects since there is no output schema. Minor gaps remain around output format or precise metric definitions, but they do not prevent 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 description coverage is 100%, so the schema already documents every parameter. The tool description adds no parameter-specific guidance 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 clearly enumerates the specific data topics (labor force, unemployment, commute times, public transit usage, work-from-home rates) and the geographic scope (US geography), which distinguishes it from sibling census_* tools. It lacks an explicit verb like 'returns' or 'provides', but the intent is 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 gives clear use contexts: site selection, workforce analysis, and commercial real estate. This helps an agent decide when this tool is relevant, though it does not explicitly state when to use an alternative census tool or call out exclusions.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context by stating the source is ACS 5-year and listing the returned fields, but it does not disclose potential limitations such as data suppression, margins of error, or geography-specific availability.

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 core purpose, and includes a compact list of return fields plus the data source. Every sentence adds 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?

There is no output schema, but the description enumerates the returned counts and median age, which is adequate for a read-only demographic lookup. The schema handles parameter semantics, and the source attribution provides important temporal context, though a note on ACS estimate reliability would improve completeness.

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 fully documents all 8 parameters with descriptions and an enum for level, so the description does not need to repeat parameter details. The description adds only general geography context, which is insufficient to raise the score above the baseline.

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 specific purpose: providing race, ethnicity, and age breakdowns for US geographies. It lists the exact returned metrics and names the data source, making it easily distinguishable from sibling census tools that focus on population, income, or business data.

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 for when the tool is relevant: when demographic breakdowns by race, ethnicity, or age are needed. It does not explicitly name alternatives or exclusions, but the detailed output list makes the appropriate use case evident.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context about matching behavior, especially the note that state lookups support substring matching. It does not contradict 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?

Three sentences, each earning its place: what the tool does, what inputs it supports, and why/when to use it. The purpose is front-loaded and no filler is present.

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 simple lookup tool with strong schema coverage and safe annotations, the description is adequate for selection and invocation. The only minor gap is that it does not describe the exact response shape or how ambiguous matches are handled, but no output schema exists and the purpose is simple enough that this is not a serious deficiency.

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 describes all three parameters in detail, including query examples, the level enum, and the limit default. The description adds only minor extra meaning—substring matching for states—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 ('Look up'), a clear resource ('Census FIPS codes by name'), and enumerates supported query forms. It also distinguishes itself from the other census_* tools by identifying it as the code-finding helper needed before those data tools.

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 guidance: 'Use this to find the FIPS codes needed by other census_* tools.' This tells the agent when to reach for it, though it stops short of explicitly naming alternatives or stating when not to use it.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds metric and geography scope but does not disclose operational behavior such as return shape, aggregation, wildcard effects, or lookup defaults. 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 two sentences with front-loaded, specific metric content followed by a short use-case statement. It contains no filler, no repetition of schema details, and 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?

The schema fully documents all conditional geography parameters and the annotations cover read-only/idempotent behavior, so most invocation requirements are already structured. The description adds the output metrics and use cases, which is valuable because there is no output schema. A small note on how to choose among geography levels would improve it further.

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 each parameter already has a meaningful description including conditional requirements and wildcard usage. The description adds no parameter-specific semantics beyond the general geography scope, 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 names a specific data domain—household income, per capita income, housing units, occupancy, home value, and rent—for US geographies. This concrete metric list makes the tool's purpose clear and distinguishes it from sibling census tools like census_demographics or census_population without opening the schema.

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

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

The description gives explicit use cases ('real estate AI, market analysis, location-based pricing'), which provides useful context. However, it does not compare against sibling census or real-estate tools, nor does it say when not to use this tool, leaving alternative selection to inference.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds meaningful behavioral context by listing the returned metrics (total, male, female, median age) and the supported geography scope. This helps the agent predict what the call will produce without an output schema.

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 wasted words: action and scope first, then return values, then use cases. It is appropriately sized for a data-retrieval tool and front-loads the most important 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?

The description covers the core outputs, supported geographies, and typical use cases, which is sufficient given the rich schema and read-only annotations. It could be slightly more complete by explicitly differentiating itself from census_demographics, but an agent can still invoke it correctly with the schema's parameter descriptions.

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 8 parameters and their conditional requirements. The description adds little parameter-specific meaning beyond restating geography levels, which are already captured in the level enum and parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Get total population for a US geography,' then enumerates all supported geography levels. It also distinguishes itself from sibling census tools by specifying the exact outputs (total, male, female, median age), which clarifies its narrow population-focused scope.

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 usage context by stating it is 'Used for market sizing, location intelligence, demographic analysis.' It does not explicitly name alternative tools or exclusion criteria, but the use cases give an agent enough context to select it over broader census or demographic tools.

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 destructiveHint false, so the safety profile is covered. The description adds that results are aggregate counts by a single facet, but it does not disclose output structure, limits, sorting, or other behavioral nuances. There is no contradiction with 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 two sentences with no filler: it opens with a precise statement of what the tool does, enumerates the facet options, and closes with relevant use cases. Every sentence contributes useful 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?

For a two-parameter read-only aggregation tool with a complete schema and safety annotations, the description is largely sufficient: it names the facets, describes the output concept (aggregate counts), and gives practical use cases. Since there is no output schema, a slightly more explicit description of the response shape or ordering would make it fully complete, but this is a minor gap.

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 documents both parameters fully, including an enum for facet and a description for company, so schema coverage is 100%. The description reinforces the meaning of the facet parameter by listing valid values and stating the use cases, but it does not add substantial semantic detail beyond the schema.

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

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

The description states a specific verb and resource ('Aggregate complaint counts') and enumerates the exact allowed facets, making the tool's function immediately clear. It is clearly distinguishable from sibling tools like cfpb_complaint_detail, cfpb_search_complaints, and cfpb_complaint_trends because it focuses on single-facet aggregation rather than individual records, search, or time trends.

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 concrete use cases ('ranking companies by complaint volume' and 'finding the most common issue categories'), which gives useful context for when to invoke it. However, it does not explicitly mention alternatives or exclusion conditions, such as when to prefer cfpb_complaint_trends or cfpb_search_complaints instead.

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, idempotentHint, and non-destructive behavior. The description adds useful context beyond annotations by disclosing that the full record includes the narrative only 'if consented,' which is a meaningful behavioral caveat for a complaint detail endpoint.

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 short sentences with no filler. The main action and resource are front-loaded, and the conditional narrative detail is stated efficiently in the second sentence.

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

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

For a simple single-ID lookup tool with safe annotations, the description is largely complete: it names the required parameter, the return type ('full record'), and a key conditional field ('narrative if consented'). It does not describe error/not-found behavior, but that is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100% and the single parameter is already described as 'CFPB complaint ID.' The tool description adds no additional format, source, or lookup semantics beyond what the schema provides, so the baseline score 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?

The description clearly states a specific verb ('Fetch'), a specific resource ('a single CFPB complaint'), and the lookup key ('complaint_id'). It also distinguishes itself from sibling search/aggregation tools by emphasizing 'single' and 'full record'.

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 conveys clear usage context: use this when you have a complaint_id and need the full individual record. It does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a 5, but the intended use is evident.

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 that this is read-only, idempotent, and non-destructive, so the description does not need to repeat those safety traits. It adds some behavioral context by explaining lens semantics and interval options, but it does not describe output format, default behaviors like trend_depth, or parameter interactions.

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 no filler. The main purpose is front-loaded, and the lens and interval options are enumerated compactly. Every word contributes useful 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?

For a tool with seven parameters and no output schema, the description is adequate but leaves gaps. It does not clarify how sub_lens interacts with lens, whether product filters combine with lens=product, or what the returned trend data actually looks like. Schema coverage helps, but sub_lens remains ambiguous.

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 has 100% description coverage, so the baseline is 3. The description adds value beyond the schema by explaining the meaning of each lens enum value and clarifying that interval can be month, quarter, or year. This helps an agent use the most important parameters correctly, though it adds nothing for sub_lens or product filters.

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 purpose: 'Time-series trends of complaint volume.' It further specifies what each lens shows, including totals over time and breakdowns by product, company, or issue, which makes it easy to distinguish from sibling complaint tools like cfpb_search_complaints or cfpb_complaint_detail.

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 explains the available lenses and intervals, so an agent can infer when to use this tool for time-series trend analysis. However, it does not explicitly state when to prefer this tool over alternatives such as cfpb_complaint_aggregations or cfpb_state_complaints, nor does it mention any exclusions.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful context about the database's scale, time range, and the availability of public narratives in results, but it does not disclose pagination, rate limits, or other behavioral edge cases beyond what the schema's default/max values already 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?

Two tightly written sentences front-load the core purpose and resource, then list the filter dimensions and return value. There is no filler or redundant restatement of the tool name or annotations.

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

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

For a search tool with 9 optional parameters and no output schema, the description gives a solid high-level picture of inputs and outputs. However, it does not orient the agent among the many related CFPB sibling tools, such as cfpb_complaint_aggregations, cfpb_complaint_trends, or cfpb_suggest_company, leaving some selection context to the agent's own reasoning.

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 every parameter. The description paraphrases several filters (free-text term, company, product, state, date range, narrative-presence) but adds no new semantic detail beyond what the schema provides, matching the baseline of 3.

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 a specific action ('Search'), a specific resource (the CFPB Consumer Complaint Database), and the main filtering capabilities. It does not explicitly distinguish itself from sibling tools like cfpb_complaint_aggregations, cfpb_complaint_trends, or cfpb_state_complaints, so it falls short of a 5.

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

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

The description implies when to use the tool: when you want raw complaint records matching certain filters. However, it provides no explicit when-not-to-use guidance or direct comparison with alternatives such as cfpb_complaint_aggregations for counts or cfpb_complaint_detail for individual complaint details, leaving the differentiation to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds that the output consists of counts and percentages per state, but it does not clarify what the percentages are relative to, how missing states are handled, or how date-range bounds behave. This is acceptable but minimal.

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 no filler. The first sentence states the core function and output, and the second provides a concrete use case. Every phrase earns its place and the most important 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?

For a tool with no required parameters and no output schema, the description gives a reasonable high-level understanding of return values and filters. However, it does not specify the output structure, whether all states are always returned, or how this tool differs from nearby CFPB siblings, leaving some ambiguity for an agent navigating a large tool catalog.

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 product, date_received_max, and date_received_min. The description only restates that there is an optional product filter and date range without adding deeper semantics such as allowed product values or date-format constraints 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?

The description clearly identifies the tool as returning complaint counts and percentages per US state, with optional product and date filters. This is specific enough to distinguish it from generic complaint search tools, though it doesn't explicitly name or differentiate from sibling aggregation tools like cfpb_complaint_aggregations or cfpb_complaint_trends.

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 offers a clear use case ('state-level financial-consumer risk maps'), which implies when this tool is appropriate. However, it gives no explicit guidance on when not to use it or which sibling tool to prefer for other aggregation styles, such as national or time-series breakdowns.

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 destructiveHint=false, covering the safety profile. The description adds behavioral details beyond that: it returns up to 10 suggestions, matches partial input, and produces values suitable for a specific sibling parameter. This is useful context, though it does not reveal ordering, matching rules, or empty-result 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?

Two sentences with no wasted words. The core behavior and result limit are front-loaded, and the downstream usage note is concise and actionable.

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 one-parameter autocomplete tool with strong safety annotations and no output schema, the description provides the essential return-value information (up to 10 suggestions) and integration guidance. It is nearly complete; minor details like whether suggestions are full names or formatted strings could be added, but 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 schema already documents the only parameter 'text' as 'Partial company name' with 100% coverage. The description reinforces the partial-input concept but adds little meaning beyond the schema, 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 clearly states a specific action ('auto-complete company names') and resource ('company names'), and specifies the output behavior (up to 10 suggestions matching partial input). It also distinguishes itself by pointing to its intended downstream consumer, cfpb_search_complaints, so an agent can tell it apart from complaint-search siblings.

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

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

The description gives explicit context: use this tool to generate exact values for cfpb_search_complaints' company parameter. This effectively tells the agent when and why to use the tool, though it does not explicitly state when not to use it or name alternative suggestion/fuzzy-match tools.

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; description adds data source, keyless access, graceful missing-data behavior, and a caveat that results are not an SDS. This complements the annotations without contradiction.

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 containing only necessary information: what it returns, how missing data is handled, and a safety caveat. 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?

For a single-parameter, read-only lookup, the description covers input format, output content, missing-data behavior, and usage caveat. No important operational detail 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 covers the single 'query' parameter 100%, so baseline is 3. The description repeats the name-or-CID input form but adds no new parameter-level detail beyond the schema.

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

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

States a specific verb (return), resource (GHS hazard classification), and source (PubChem). The description explicitly names the outputs (signal word and hazard statements), making its purpose unmistakable and distinct from a generic chemical_lookup sibling.

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

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

Does not name an alternative tool, but clearly frames the use case: retrieving public GHS classification data from PubChem. It adds a boundary condition with the SDS disclaimer, telling the agent this is informational and not regulatory guidance, though it doesn't explicitly route to alternates.

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, openWorldHint, and destructiveHint=false. The description adds valuable context about the NIH/NLM PubChem public database, keyless access, public-domain data, and the stability of the returned CID. 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?

The description is three sentences, each earning its place: what it resolves, what it returns, and when to use it. The action is front-loaded and there is no filler or redundant wording.

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 one-parameter, read-only tool with rich annotations and no output schema, the description fully covers the return fields, data source, access model, and primary use case. An agent has sufficient information to select and correctly invoke this tool.

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

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

The input schema covers 100% of the single parameter and already explains that query accepts a chemical name or numeric PubChem CID. The description repeats those examples but adds no parameter-specific meaning beyond what the schema already provides.

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 ('Resolve') and a clear resource: chemical names or PubChem CIDs to identity and physical properties. It lists the concrete return fields, making the tool's scope unambiguous. This clarity separates it from sibling chemical_hazards, which is focused on hazard data.

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 explicitly says to use it to disambiguate a substance and obtain a stable CID join key for further chemistry or safety lookups. It does not name an alternative sibling tool or give when-not-to-use conditions, so it falls just short of complete 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, openWorldHint, idempotentHint, and non-destructive behavior, so the description only needs to add behavior beyond those. It does: it names the three keyless sources, explains exact recruiting counts vs. national totals, describes the heuristic condition-to-specialty mapping with an explicit override, notes graceful Census-key degradation, and states that source failures are non-fatal. This is strong behavioral disclosure with no contradiction.

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 first clause front-loads the core purpose, and the rest is information-dense rather than padded: sources, outputs, failure behavior, and caveats all earn their place. The source enumeration is slightly run-on, but there is no wasted content.

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 and a complex three-source data aggregation, the description still explains what the agent will receive, including a readable brief with HIGH/MODERATE/LOW/NONE trial-activity banding and specialist availability. It also covers source-failure handling, the Census key prerequisite, and the informational-not-medical-advice boundary, making it complete enough to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: condition is heuristically mapped to a provider specialty, specialty overrides that mapping, city/state scope the trial and provider search, and the Census component is optional and needs a key. This helps an agent choose and combine parameters 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 states a specific composite verb+resource: a one-call read of clinical-trial activity plus local specialist availability for a medical condition in a US geography. It clearly identifies the audience and decision context, and it is distinguishable from siblings like trials_search, npi_search_provider, and census_population because it is explicitly a combined site-feasibility synthesis.

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 and concrete usage context: trial sponsors, CROs, or site-feasibility analysts deciding where to run a study. It does not explicitly name excluded cases or alternatives such as 'use trials_search for raw trial data,' but the intended situation is strongly implied and 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 establish the read-only, idempotent, non-destructive nature. The description adds value by disclosing the expected return contents (name, address, services, quality ratings), which is useful because there is no output schema. It does not mention rate limits or auth, but for a simple read-only search tool this is acceptable.

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 short sentences with no filler. It front-loads the core action and resource, then quickly lists the useful output fields. Every word 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?

For a simple optional-parameter search tool, the description is complete: it names the source dataset, the target population, and the return fields. The input schema covers filtering and pagination parameters, and the annotations cover safety and idempotency, so 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?

All four parameters have descriptions in the input schema, so the schema carries full parameter documentation. The tool description adds no additional parameter-level meaning beyond the general search domain, which matches the baseline score of 3.

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 ('Search') and a specific resource ('Medicare-certified home health agencies from CMS Home Health Compare'), and it names the returned data types: agency name, address, services offered, and quality ratings. This clearly distinguishes it from sibling tools like cms_hospital_search or cms_nursing_home_search.

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 establishes when this tool is relevant: whenever the user needs Medicare-certified home health agencies from the CMS Home Health Compare dataset. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of a 5, but the 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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds scope (Medicare-certified, CMS Hospice Compare) and return-field information, but doesn't disclose operational behavior such as pagination, update cadence, or response structure; that's modest context beyond 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?

Two short sentences with no filler. The main verb and resource are front-loaded, followed immediately by the return content, and every word contributes.

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 and four optional parameters, the description usefully names the return categories and source, while the schema fully documents parameter meanings. Nothing needed to select and call 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 all four parameters (limit, state, offset, name_contains) are already documented with clear meanings and defaults. The tool description adds no parameter-specific semantics beyond naming the search resource, so it stays at the baseline for high schema coverage.

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 ('Search'), a concrete resource ('Medicare-certified hospice agencies'), and the data source ('CMS Hospice Compare'). It also lists expected return fields, and the hospice-specific wording distinguishes it from sibling CMS facility-search tools without needing to inspect their schemas.

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 intended use is inferable from 'hospice agencies' and 'CMS Hospice Compare', but the description never explicitly contrasts it with cms_hospital_search, cms_nursing_home_search, or cms_home_health_search, nor gives when-not-to-use conditions. This is clear implied context rather than explicit 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 establish that the tool is read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that: the specific return fields, the dataset source, and the supported filtering dimensions. It does not mention pagination or rate limits, but for a simple read-only search that gap is minor.

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 no filler. It front-loads the core purpose, then efficiently packs return fields and filter dimensions into a single follow-up sentence.

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

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

For a read-only search with all-optional parameters and no output schema, the description covers the essential facts: the source dataset, the return fields, and the filter criteria. Pagination defaults and exact output structure are left to the schema and general conventions, but those are minor omissions given the tool's simplicity.

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 fully documents state, city, limit, offset, and name_contains. The description restates state/city/name filters in plain language but adds little semantic meaning beyond what the schema provides.

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: 'Search Medicare-certified hospitals from the CMS Hospital General Information dataset.' It clearly states what the tool returns and what filters are available. The word 'hospitals' distinguishes it from sibling tools covering home health, hospice, and nursing homes, even without naming them 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?

The description provides clear operational context: use this search when you need hospitals filtered by state, city, or partial facility name. It does not explicitly name alternative tools or state when not to use it, which keeps it just below a full routing guideline.

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, openWorldHint, idempotentHint, and non-destructive behavior, and the description does not contradict them. It adds value by specifying the return payload and the source dataset, which helps an agent anticipate output. It does not describe pagination behavior, but offset and limit are documented in the schema.

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 with roughly 20 words, front-loading the action and resource while every phrase contributes either scope or return information. There is no filler, no repetition of the schema, and no redundancy with annotations.

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

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

For a simple read-only search with fully documented optional parameters and no output schema, the description is nearly complete: it states the source, target entity type, and principal fields returned. It could explicitly mention pagination or default behavior, but the schema already provides defaults for limit and offset, so no critical invocation 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%; all four parameters (limit, state, offset, name_contains) already have meaningful descriptions. The tool description adds no parameter-level meaning beyond what the schema provides, 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 opens with a specific verb ('Search') and a concrete resource ('Medicare-certified nursing homes from CMS Nursing Home Compare'), and lists the returned fields including name, address, ownership, certification status, total beds, and quality measures. This clearly differentiates it from sibling tools such as cms_hospital_search or cms_home_health_search.

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 establishes clear context: this tool is for Medicare-certified nursing homes sourced from CMS Nursing Home Compare, so an agent searching for nursing home facilities can identify it. It does not explicitly name alternatives or state when not to use it, but the resource scope is unambiguous and the sibling tool names reinforce the distinction.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds the useful caveat that last action date and programmatic accreditations are included only when published by DAPIP, giving the agent awareness that these fields may be absent. This is helpful context but not extensive behavioral disclosure.

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 a single, compact sentence with no filler. It front-loads the core purpose ('Current institutional accreditation status') and packs the additional fields and DAPIP caveat efficiently.

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 one-parameter, read-only lookup with no output schema, the description covers what data will be returned and the key condition under which some fields are available. Nothing needed to invoke 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?

The single parameter unit_id is already fully described in the schema as 'IPEDS UNITID' (100% schema description coverage). The description does not add further parameter details, 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 clearly identifies the resource (institutional accreditation) and enumerates the returned data: status, accreditor, last action date, and programmatic accreditations. It does not use an explicit verb like 'gets' or 'returns,' but the intent is unmistakable and it is distinct from sibling college_* tools that focus on search, metrics, or outcomes.

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 no guidance on when to use this tool versus related siblings such as college_search, college_metrics, or college_compare. There are no explicit when-to-use conditions, exclusions, or alternative tool names, so an agent must infer suitability from the name alone.

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 readOnlyHint, idempotentHint, and destructiveHint annotations already communicate that the call is safe and repeatable, so the description does not need to cover side effects. It adds modest context by naming the comparison dimensions, but it does not disclose return format, output size, or behavior with invalid UNITIDs.

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 entire description is one front-loaded sentence: the verb and object first, then the scope and metric dimensions, then the input instruction. There is no filler or redundant elaboration.

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 one-parameter, read-only tool with a fully documented schema, the description supplies enough context to identify the tool and invoke it correctly. A small gap is that it does not suggest how to discover UNITIDs (e.g., via college_search) or describe the response format, but neither is required to make a safe call.

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 gives 100% parameter coverage with 'Array of 2-5 IPEDS UNITIDs.' The description only repeats 'Pass UNITIDs' and adds no extra semantics about how to obtain or format those IDs.

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 the specific verb 'comparison', names the resource ('schools'), and constrains the scope to 2-5 schools and three metric categories. This is enough to distinguish it from college_search, college_metrics, and other single-school sibling tools.

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

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

Usage is only implied: an agent can infer that this is the right tool when a user asks to compare multiple schools side by side. It does not name any alternative tool or give a when-not-to-use condition, even though siblings like college_metrics or college_value_score could overlap.

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, so the safety profile is covered. The description adds useful context about what demographic dimensions are included, but it does not disclose behavior around missing data, invalid unit IDs, or the response format. This is acceptable given the strong annotation coverage.

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 a single, well-structured sentence that front-loads the core purpose ('Student-body demographics for one school') and then compactly lists the demographic categories. Every word contributes meaning, with no filler or redundant restatement.

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 simple single-parameter lookup tool with rich annotations and no output schema, this description is largely complete: it names the school identifier, the single-school scope, and the demographic dimensions returned. It does not detail formatting or data source, but these are minor gaps for such a straightforward 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 input schema covers 100% of the single parameter, unit_id, with a description 'IPEDS UNITID.' The tool description does not add significant parameter-level detail, but none is needed since the schema fully documents the parameter. 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 identifies the resource as student-body demographics for a single school and enumerates the specific demographic categories covered (race/ethnicity, gender, age, geographic origin). It distinguishes itself from sibling tools like college_compare or college_trends through the 'for one school' scope, though it does not explicitly name any sibling.

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

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

The phrase 'for one school' implies this tool is for retrieving a single institution's demographic breakdown, as opposed to comparing or searching across schools. However, it does not explicitly state when to use this tool over siblings like college_metrics or college_compare, nor does it provide exclusion criteria.

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, so the safety profile is well covered. The description adds the list of returned metrics, which is useful, but does not disclose behavioral details such as data source, update frequency, or handling of missing metrics.

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 a single, well-structured sentence that front-loads the tool's purpose ('Cost and outcome metrics for one school') and then lists the specific metrics. There is no redundant or filler content.

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 simple one-parameter lookup with rich annotations and no output schema, the description works as a de facto output contract by naming every metric returned. It lacks caveats around data availability, but nothing essential seems 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 description coverage is 100%, with unit_id documented as the IPEDS UNITID (Scorecard 'id'). The tool description does not need to add parameter semantics, and it does not attempt to; the schema adequately carries this information.

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 as returning cost and outcome metrics for a single school, and enumerates the specific metrics included. It differentiates from broader sibling tools like college_trends and college_compare by scoping to 'one school,' though it does not name those alternatives 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?

The intended use is implied: call this when you need tuition, graduation, earnings, admission, or SAT/ACT metrics for one institution. However, there is no explicit guidance on when to prefer it over related sibling tools such as college_compare, college_demographics, or college_value_score.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful semantic detail about the metrics ('one year after completion', 'at completion') but does not disclose other behavioral traits such as whether all programs are returned, how missing data is handled, or the response structure.

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 a single, tightly packed sentence with no filler. It front-loads the resource and scope before enumerating the returned metrics, making it easy to scan and understand.

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 simple one-parameter lookup with no output schema, the description provides the essential return-value details: earnings, debt, and award counts at program level. It could be slightly clearer that the tool returns data for all programs for the given school rather than requiring a CIP-code input, but the schema plus description are sufficient 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?

The only parameter, unit_id, is fully described in the schema as an IPEDS UNITID, so schema coverage is 100%. The description does not add additional parameter-level meaning, 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 precisely identifies the resource (program-level outcomes), the granularity (4-digit CIP code), the scope (one school), and the specific measures returned (median earnings, median debt, award counts). This clearly distinguishes it from sibling tools like college_metrics or college_value_score.

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

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

The phrase 'Program-level outcomes ... for one school' provides clear context for when to use this tool: when a caller needs earning, debt, or award-count metrics broken down by program. It does not name alternative tools or give explicit when-not-to-use guidance, but the scope and granularity are evident.

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 the operation read-only, idempotent, and non-destructive. The description adds useful behavioral context by specifying the return content — matching institutions with location, control, predominant degree, and enrollment — which is especially valuable given there is no output schema.

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 tightly written sentences with no wasted words. The search scope and filters lead, and the return content follows. 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?

For a simple, read-only search tool with no required parameters and fully documented schema fields, the description covers what it searches, what filters are available, and what comes back. The absence of an output schema is compensated by the description's explicit return fields.

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 every parameter. The description merely recaps the filter attributes without adding new detail about matching behavior, value formats, or combination semantics, so it earns the baseline score.

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 action ('Search US colleges and universities') and lists the available filter dimensions, making the tool's purpose clear. It does not explicitly name or contrast sibling tools like college_accreditation or college_compare, but the general lookup scope is evident from the resource and return fields.

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 this is the general-purpose college search tool — use it to find institutions by name, state, control, size, or accreditor. It provides no explicit guidance on when to prefer a sibling tool such as college_accreditation or college_outcomes_by_program, leaving the choice mostly to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds beyond the annotations by specifying the data source (Urban Institute Education Data Portal/IPEDS) and the single-school scope, which is useful behavioral context.

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 no wasted words. It front-loads the core purpose and source, then lists the parameter choices and range selection, making it easy for an agent to parse quickly.

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 annotations, complete parameter schema, and simple read-only nature of the tool, the description is largely sufficient for selection and invocation. However, there is no output schema and the description does not describe the response format or behavior for unavailable data, which is a minor gap.

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% with each parameter already described, including the metric enum and year examples. The description simply restates the metric names and 'year range' without adding deeper semantic meaning 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 clearly states the tool returns a multi-year trend for one school and identifies the data source and available metrics. It is specific enough to distinguish from college_search and college_compare, though it does not explicitly name those siblings.

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

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

The description implies when to use the tool by saying 'for one school' and instructing the user to choose a metric and year range. It does not, however, explicitly state when not to use it or point to alternatives such as college_compare for comparisons or college_metrics for other metric views.

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?

Rich behavioral disclosure well beyond the annotations: it states the exact output categories (STRONG VALUE / FAIR / WEAK VALUE / INSUFFICIENT DATA), the itemized-and-scored evidence format, graceful degradation ("A source that fails is noted, not fatal"), data limitations ("Scorecard earnings cover federally-aided students only and lag by years"), and the advisory boundary ("not admissions, financial, or career advice"). No contradiction with readOnlyHint/idempotentHint — the description explicitly calls it a "plain read."

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 ~110-word description is front-loaded with the core value proposition, then builds logically: data sources, output format, failure behavior, caveats, disclaimer. Every sentence earns its place — the parenthetical data-source details and caveats are substantive for a synthesis tool, not padding. Nothing is redundant with 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 complex cross-source synthesis tool with no output schema, the description carries the return-value burden and does so thoroughly: it names the verdict categories, explains what evidence is itemized, discloses scope limits (US, federally-aided students), and covers failure behavior. An agent can predict both the call's inputs and its response shape without opening any further documentation.

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 three parameters well, including program's role in adding "program-level debt-vs-earnings evidence" and state's disambiguation purpose. The description adds only marginal specificity — that program-level evidence consists of "median debt and 1-year earnings" — but mostly restates what the schema already conveys. Baseline 3 is appropriate; the description does not meaningfully compensate beyond the schema.

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

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

The opening phrase "One-call 'is this degree worth the cost' read for a US college (and optionally a named program)" states a specific verb (read/evaluate) with a specific resource (US college + program) and a crisp value proposition. It clearly distinguishes itself from siblings like college_metrics (raw metrics), college_compare (side-by-side comparison), college_outcomes_by_program (raw program data), and college_search (lookup), by emphasizing it is the synthesis/verdict tool rather than a raw-data tool.

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

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

The description implies usage context well — this is the one-call value judgment tool, and the phrase "when a program is named" explains the optional-program behavior. However, it never names sibling alternatives or states when to prefer college_metrics, college_compare, or college_outcomes_by_program instead, so an agent must infer the routing decision from purpose rather than receiving explicit when-to-use/when-not-to-use guidance. The "informational only" disclaimer is the only explicit exclusion.

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 readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail: it joins three public-record legs, notes that failed legs are 'noted, not fatal,' explains how recall severity (FDA Class I / death-related) factors into the rating, and clarifies that the output is an informational synthesis, not legal advice. This goes well beyond what 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 dense but every sentence earns its place: purpose, data legs, output structure, failure handling, sibling differentiation, scope exclusion, and disclaimer. It is front-loaded with the core purpose and risk signal, and the additional context is tightly packed rather than padded.

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

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

There is no output schema, so the description properly takes on the burden of explaining return values: LOW/MODERATE/ELEVATED risk read, complaint volume and top products/issues, recall count and severity, and litigation totals including last-3-years. It also covers inputs, sources, failure behavior, and exclusions. For a multi-source synthesis tool, this is comprehensive.

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 because the schema already documents all three parameters. The description adds context about how the data legs use the inputs, but it does not provide additional per-parameter meaning beyond the schema's own descriptions. It is adequate but not exceptional.

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, differentiated purpose: 'One-call CONSUMER-RISK read for a company or brand, LED by the consumer-complaint picture.' It names the exact resource and scope, and explicitly distinguishes itself from product_liability_screen and recall_screen. An agent can immediately tell this is the complaints-led risk profiling tool among many related siblings.

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

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

The description provides explicit routing guidance: it states this is consumer-complaint-centered versus product_liability_screen (recall/litigation-centered) and directs vehicle-recall use to recall_screen. It also scopes what is and is not covered, such as NHTSA vehicle recalls being out of scope without a specific year/make/model. This leaves little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds the return field list, which is useful in the absence of an output schema, but it does not disclose failure behavior, data coverage limitations, or whether fields can be null for some companies.

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

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

The description is front-loaded with the core action, then a compact field list, then example queries. Every sentence earns its place, and there is no redundant or filler content.

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 simple one-parameter, read-only tool with no output schema, the field list and example queries give an agent enough context to call it correctly and interpret the result. A minor gap is the lack of caveats about data availability or symbol validation, but these are not critical for this tool.

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

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

Schema description coverage is 100%, and the only parameter symbol is already documented as a stock ticker example ('AAPL'). The description reinforces this with Apple, Netflix, and Tesla examples but does not add meaningful parameter semantics beyond the schema.

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

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

The description begins with a specific verb and resource: 'Get company profile and financial fundamentals.' It then enumerates the exact returned fields and provides concrete example queries (e.g., 'tell me about Apple', 'what sector is Netflix in?'), distinguishing this tool from sibling tools like stock_quote or company_complaint_profile by its broad company-research scope.

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 use cases and example prompts, making it easy for an agent to route questions like 'how many employees does Tesla have?' to this tool. However, it does not explicitly say when not to use it or name alternatives such as stock_quote for price-specific queries, so it stops short of full 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 cover read-only, open-world, idempotent, and non-destructive traits, and the description adds substantial behavioral context beyond those. It discloses that a failing source is noted but non-fatal, enumerates the four verdict bands, and warns that absence of a record is not proof of wrongdoing while a match is not proof of guilt. This gives the agent a clear interpretive framework for the results.

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

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

The description is lengthy but every sentence earns its place: the one-call framing, source list, verdict bands, failure handling, and caveats all contribute to correct tool use. It is front-loaded with the essential purpose and continues with high-value detail without filler or tautology.

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