RateCard Health

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context: the payload is unredacted (full fields, exact prices) and identical to the public sample CSV, telling the agent it is a fixed, non-parameterized preview rather than a truncated query result.

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 sentence, front-loaded with the resource and its scope, with zero filler. Every clause (row count, full fields, exact prices, CSV equivalence) carries 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 no output schema, the description does its job by stating the return content: 10 rows, full fields, exact prices. What it omits is any pointer on how to get more than the sample, which would help an agent decide the next step, but 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 tool takes zero parameters, which is the baseline-4 case. The description is consistent with that — it makes clear the result is a fixed set with no filtering or paging knobs to supply.

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

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

The description names the exact resource and its scope: the 10 free sample rows of the RateCard Health database, with full fields and exact prices. An agent knows precisely what it gets back. It does not explicitly contrast with siblings like search_publications or get_publication, so it stops short of a 5.

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

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

Usage is only implied — the 'free sample' framing suggests previewing the dataset before a fuller query, but the description never says when to use this instead of search_publications or get_price_index. No exclusions or prerequisites are stated.

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

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

Adds substantial detail that the readOnly/idempotent/openWorld=false annotations do not: a minimum sample threshold ('medians only for groups with 5+ rate cards'), value rounding/banding behavior, and CC BY 4.0 licensing. These are exactly the caveats an agent needs to interpret sparse or suppressed results. Minor gap: no statement that results are a static published index rather than live data.

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

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

Two sentences, no filler, with the most decision-relevant facts (what's aggregated, granularity, filtering) up front. The parenthetical about rounding and the 5+ threshold is dense but earns its place. Slight crowding of caveats into one long sentence costs it a point.

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

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

With no output schema, the description carries the burden of describing returns and does so: medians/quartiles/CPMs, rounded or banded, minimum group size. What's missing is unit/currency and the shape of the response (flat rows vs. grouped), which matters for a filterable aggregate query.

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 50% — 'group' has only an example string and 'group_type' has only an enum with no prose. The description partially compensates by enumerating the four group_type values and framing 'group' as a group-name filter, but it never says how 'group' relates to 'group_type' (e.g. does a bare group name imply a type?). The schema does most of the work here, so baseline 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?

Opens with a specific verb+resource ('Aggregate ad-price benchmarks'), then narrows to concrete outputs (median/quartile entry prices, derived CPMs) scoped to healthcare B2B rate cards. An agent can immediately tell this is an aggregate-stats tool, not a listing tool. It never names a sibling to contrast with, though the noun phrase differs enough from get_publication/search_publications to be workable.

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

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

The only guidance is 'Optionally filter by group_type ... or group name,' which is parameter mechanics rather than tool-selection advice. Nothing says when to use this versus get_free_sample or search_publications, nor whether it is safe to call with no arguments (all params are optional, yet the description doesn't confirm the default scope).

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing the shape of the payload (price band, rate-card year, last verified date, media kit link), which tells the agent what evidence it will get back. It omits not-found/ambiguity handling, so it is not fully transparent.

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 opens with the core purpose, then enumerates fields, then closes with the lookup key. Dense but every clause carries information; the only weakness is that the long field enumeration slightly buries the parameter guidance at the tail.

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 one undocumented parameter, the description correctly compensates by listing the returned fields and the lookup modes. What remains missing is failure behavior (unknown slug, multiple partial matches) and whether the media kit link is guaranteed present — minor gaps for a single-parameter read tool.

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

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

Schema coverage is 0%, so the description must carry the parameter meaning, and it does: the single string accepts either a slug or a partial name. That partial-match capability is a genuine semantic addition an agent could not learn from the bare 'string' type. It does not specify matching rules or case sensitivity.

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

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

States a specific verb+resource ('Public details for one publication') and enumerates the exact fields returned, which clearly separates it from list-style siblings like search_publications. It stops short of naming a sibling directly, but the singular scope 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?

'Look up by slug or (partial) name' implies this is the single-record retrieval path, so an agent can infer it should reach for this after finding a publication. However, it never says when to prefer this over search_publications or what happens if multiple publications match a partial name, leaving the routing decision partly to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description earns credit by adding what the agent actually gets back — categories, format groups, counts, and page URLs — which is not available from annotations or 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?

A single sentence with no filler, front-loading the action and resource before the payload details. Every clause carries 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 zero-parameter, read-only listing with no output schema, the description conveys enough about the return content to call it confidently. Minor gaps remain (no hint about ordering, pagination, or URL format), but nothing essential is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for parameterless tools applies. Nothing in the description misleads about 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?

States a specific verb and resource ('List the publication categories and format groups') and even names the returned payload (counts, page URLs). It is clearly distinct from siblings like search_publications or get_publication, though it never explicitly says so.

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 this is a discovery/enumeration call useful before searching, but the description never states when to call it or how it relates to the sibling search/get 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, closed-world, non-destructive behavior, so the description's burden is lighter. It still adds a genuinely important data-fidelity caveat: entry ad price is a BAND, exact only for the 10 free-sample rows — exactly the kind of context an agent would otherwise misreport. It omits pagination/limit behavior, but the schema documents the default.

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

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

Two sentences, both earning their place: the first establishes corpus and filter axes, the second enumerates return fields and the price-band caveat. Front-loaded with the resource identity and no filler.

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

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

With no output schema, the description correctly takes on the return-value burden and lists name, publisher, category, format, circulation/open rate, price band and page URL. What's missing is minor but real: result-count defaults and whether/how results are ordered when many match.

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 are already documented with defaults, bounds and allowed values. The description's category and format examples largely restate the schema enums, and its query gloss ('name, publisher, audience') is actually narrower than the schema's ('...and sub-vertical'). 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 (Search) and a precisely bounded resource: the RateCard Health index of healthcare B2B trade publications, association e-newsletters and journals carrying ad rate cards. It also enumerates the filter axes and the returned fields, so an agent knows exactly what corpus it is querying. It stops short of naming how it differs from get_publication or get_price_index, which the verb alone only implicitly handles.

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?

'Filter by category ... format ... and/or a free-text query' makes clear the filters are combinable and all optional, which is the main usage decision for this tool. It gives concrete example categories and formats, but offers no when-not guidance and does not route the agent to get_publication, list_categories, or get_price_index for the cases those cover.

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