MRR Ledger

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

Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds meaningful context beyond them: no storage of MRR, free usage with a daily cap, lack of growth numbers, and peer caveats. This is unusually transparent for a benchmark tool.

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

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

Front-loads the use case, then gives the return shape, caveats, and cost without padding. Every sentence contributes useful selection or invocation context.

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 full schema coverage, existing output schema, and informative annotations, the description is complete enough for an agent to call correctly. It covers scope, limitations, cost, privacy, and output expectations.

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 parameter definitions already do the heavy lifting. The description adds an example input mapping but does not explain the optional parameters or add semantics beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource: benchmarking the user's MRR against same-category peers. The example and the "rank of N + 1 comparable" phrase make the returned concept concrete, so an agent can distinguish it from generic business lookup or growth 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?

Explicitly says to use it when the user provides their own MRR or asks whether revenue is good versus similar AI businesses. It does not name alternatives or exclusions, but the user-supplied MRR condition is a clear routing cue.

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, so the safety profile is covered. The description adds value beyond that: it enumerates the returned fields (tier, category, revenue + basis, pricing model, founded, lessons, growth), the diff with revenue ratio, and a cost/rate limit of 100 calls/day without a key.

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

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

Front-loaded with the "Use when..." trigger, followed by return contents, a compact example, and cost. No padding; every clause carries actionable 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 an output schema present the description needn't detail return shapes, yet it still summarizes the payload and diff, and it covers triggering, inputs via example, and quota. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both params are documented as business slugs, and the worked example {"a":"cursor","b":"lovable"} reinforces the expected slug format and which param is which side of the comparison. It adds modest but real meaning over the schema 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?

States a specific verb (compare) and resource (two AI companies) with the dimensions compared (revenue, business model). It is clearly distinct from siblings like get_business (single lookup) and benchmark_business, so an agent can route without opening 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?

"Use when the user asks to compare two AI companies (X vs Y) on revenue or business model" gives an explicit trigger condition. It does not name alternatives or exclusions (e.g. what to use for a single company or for non-revenue comparisons), 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?

Beyond the readOnly/idempotent annotations, the description discloses the paid x402 model, per-format pricing, that unpaid calls return a free preview and exact terms, and that nothing is charged without a signed payment. It also provides a free 10-row preview link, which is substantial behavioral context an agent needs before invoking a paid tool.

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

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

The content is front-loaded with the return payload, then pricing, then payment safety, then preview — a logical order. It is dense with parenthetical clauses, but each sentence carries distinct, necessary information about a paid tool; only minor tightening would help.

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 usefully sketches return fields (as-of date, source_url, dated readings) and pricing, so an agent knows what it gets. For a 2-param read-only export, this is nearly complete; the only minor gap is not clarifying whether a per-row or per-slug charge applies to repeated calls (idempotency is annotated, so acceptable).

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 documents slug but not format, so 50% coverage leaves format undocumented structurally; the description fills that gap by pricing each format and noting slug scopes to a single business at the same price. It adds real meaning beyond the schema, though it does not restate slug's 'tracker businesses only' constraint explicitly (that remains in 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 ('Returns the Reported AI Revenue Tracker in one call') and immediately qualifies the dataset's provenance ('figures all come from press coverage, company announcements or filings... reported, not payment-verified'). That distinction clearly separates this export from the business/category/growth lookup siblings, which return individual records rather than a full reported-figures 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?

It gives concrete usage context: choose format csv or jsonl, optionally scope to one business via slug, and an unpaid call yields a free preview plus exact terms. It stops short of explicitly naming when to prefer this over sibling tools like get_business or search_businesses, but the export-vs-lookup framing is clear from the content described.

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 read-only/idempotent annotations, it discloses return contents (dated revenue figures with label/value/as_of/source_url, growth series, related businesses), error behavior on unknown slug, and cost/rate limit (free, 100 calls/day without a key). That is exactly the operational context annotations cannot carry.

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

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

Front-loaded with the trigger condition and zero filler, but the enumerated return-field list is dense and partly redundant with the output schema, slightly inflating length.

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?

Covers trigger, scope, payload shape, error semantics, and rate limits; with an output schema present, return-value detail is a bonus rather than a gap. An agent has everything needed to call it correctly on the first attempt.

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 value by showing an input->output mapping ({slug: cursor} -> full Cursor record), confirming the slug is a canonical short identifier rather than an ID or name.

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 ('Returns one business's full sourced record') and grounds it with concrete examples (Cursor, Lovable) plus a literal call example. Clearly distinguishable from list/leaderboard/compare 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?

Explicit trigger condition: 'Use when the user names one AI company or agent ... and asks about its revenue, pricing model or growth.' It also covers the failure path (unknown slug -> isError). It stops short of naming the sibling to use when no specific company is named, which is left to the schema's slug hint.

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, so the safety profile is covered. The description still adds non-obvious behavior: unknown slugs produce an error rather than an empty result, and there is a free tier of 100 calls/day without a key — genuine rate-limit disclosure that the schema does not carry.

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

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

Two sentences, front-loaded with what is returned, followed by a concrete example, the error case, and cost. No filler; every clause carries information the agent can act on.

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

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

With an output schema present and a fully documented single parameter, the description needs only to cover errors and limits, which it does. The remaining gap is not pointing at list_categories as the way to obtain a valid slug before calling.

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 a single documented 'slug' property including example values, so the schema does the heavy lifting. The description's example mapping adds only marginal meaning beyond it, which is the baseline-3 case.

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 ('Returns one category') and enumerates the payload (count, median annualized revenue overall and by tier, ranked members), which sets it apart from list_categories and the business-level get_business tool. The 'one category' framing makes the singular-vs-list distinction obvious.

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 worked example ({"slug":"customer-support"} -> the customer-support agents) plus the 'Unknown slug -> isError' note gives clear invocation context. It stops short of explicit routing guidance, e.g. that list_categories should be used to discover valid slugs before calling this.

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

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

Beyond the annotations (which already declare readOnly/idempotent/non-destructive), the description discloses ordering ("oldest first"), normalization ("MRR x12"), error behavior ("Unknown slug -> isError"), and a concrete rate/cost profile ("free, 100 calls/day without a key"). These are non-obvious operational facts an agent needs before deciding whether to call or fan out.

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 trigger condition and core behavior are front-loaded in the first two sentences, and the example plus cost note are compact and useful. The parenthetical field list and nested parentheses make the final sentences denser than necessary, though nothing is truly wasted.

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

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

An output schema exists, so return values need no full prose explanation, and the description still covers ordering, normalization, error handling, and cost. For a one-parameter read-only tool this is everything an agent needs to call 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 coverage is 100% and the single parameter is already documented, so baseline would be 3. The description adds value by supplying a concrete example mapping {"slug":"lovable"} to Lovable's ARR points and by defining the failure case for an unrecognized slug, which the schema does not 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+resource: it returns one business's dated revenue series, and it names the triggering user intent ("how fast an AI company grew or for its revenue over time"). The phrase "one business's" implicitly separates it from siblings like compare_businesses and benchmark_business, so an agent can route without opening a schema.

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

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

It gives an explicit trigger condition ("Use when the user asks how fast an AI company grew or for its revenue over time"), which is clear context for selection. It does not explicitly name or exclude the alternatives (compare_businesses, get_business), so the agent must infer the boundary from "one business".

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, so the bar is lower. The description adds real value beyond them: the error behavior for unknown slugs and the free-tier cost (100 calls/day without a key).

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?

Compact and front-loaded: what it returns first, then example, then error case, then cost. Every clause carries information, though the inline JSON example is slightly noisy.

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

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

An output schema exists, so return values needn't be explained, yet the description gives a useful summary anyway. Error behavior and rate limits round out what an agent needs for this simple 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 100% and the single slug parameter is already documented with the same example values the description repeats, so little is added. The example mapping {"slug":"trustmrr"} reinforces the semantics but is largely duplicative.

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 ("Returns one tag") and enumerates the payload fields (count, median annualized revenue, members with rank and revenue), so the agent knows exactly what it gets. Sibling differentiation is absent: nothing distinguishes it from get_category or list_tags.

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

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

Provides a concrete lookup example and the failure condition (unknown slug -> isError), which implies when to use it. It never states when to prefer list_tags or get_category, so routing between siblings is left 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: it is free and capped at 100 calls/day without a key, which matters for call budgeting. It also preempts the empty-argument call pattern, though the field preview overlaps with the 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?

Three short sentences, front-loaded with the returned aggregates, then a call-shape example, then the cost caveat. No filler and no restatement of the title. Each sentence carries distinct information.

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

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

An output schema exists, so the description need not fully document return values, yet it names the key fields, gives the empty-argument call shape, and discloses the rate limit. For a zero-parameter read-only aggregate tool that is everything an agent needs before invoking.

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 per the rubric the baseline is 4. The description correctly communicates that the call takes an empty object ('Example: {} -> ...'), which prevents an agent from hunting for filter arguments. Nothing further is needed.

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 (dataset totals) and enumerates the aggregates returned — business/ranked/lesson counts, per-category and per-tier breakdowns, median revenue, verified share. An agent can tell this is the dataset-wide summary tool rather than a per-business or list tool from the sibling set. It stops short of explicitly naming the siblings it displaces (e.g. leaderboard, search_businesses) as alternatives.

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 enumerated aggregates signal 'use this for an overview or baseline before drilling into individual businesses.' There is no explicit when-to-use, when-not-to-use, or named alternative. The cost note (free, 100 calls/day without a key) gives the agent a practical budget signal but does not route it between 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 and closed-world, so the lower bar applies. The description still adds real value: sort direction, output shape ('briefs as in search_businesses'), the 50-item cap, and cost/rate limit (free, 100 calls/day without a key).

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

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

Front-loaded with the usage trigger, then result semantics, then filters and cost, all in one tight paragraph plus a compact example. Dense but every clause carries information; a light structure (e.g., separating cost) would be the only improvement.

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

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

Output schema exists so return values needn't be detailed, and the description still covers ordering, filter set, cap, and cost. For a zero-required-param ranked-list tool with full schema coverage and annotations, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3; the description goes beyond by showing a concrete example invocation and clarifying the limit ceiling, and it points to list_categories for valid category slugs. The verified_only semantics are left to the schema, which already documents them.

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 ranked resource ('Returns businesses ranked by latest sourced annualized revenue, highest first') plus the user question it answers. It distinguishes itself from search_businesses by noting the brief format matches but is ranked by revenue.

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?

Opens with an explicit trigger ('Use when the user asks which AI agents or AI startups make the most money, or for a top-N revenue ranking') and mentions search_businesses as the related retrieval tool. It does not explicitly state when to prefer search_businesses or compare_businesses instead, so routing is clear but not exhaustively delimited.

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 annotations already declare readOnlyHint, idempotentHint, non-destructive behavior, and openWorldHint=false. The description adds useful context beyond the annotations: returned fields, a limit example, and the cost model (“free, 100 calls/day without a key”).

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 short, front-loaded with the purpose and return contents, and uses a compact example plus cost note without wasted 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 simple read-only list tool with one optional parameter, rich annotations, and an output schema, the description covers purpose, return fields, limit usage, and cost. Nothing critical 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?

Schema description coverage is 100%, and the single limit parameter is already documented as “Max categories to return (default: all).” The example adds a small illustration of limiting results, but does not materially expand 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 states a specific verb/resource: it returns every category with count, median annualized revenue, and member details. This clearly distinguishes it from a single-category lookup like get_category, though it does not explicitly name sibling alternatives.

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

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

Usage is implied by “Returns every category” and the limit example, which shows how to retrieve only the first N categories. However, it does not explicitly state when to use this tool versus get_category or other category-related siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds non-obvious behavior: default sort order ('most used first') and a cost/quota constraint ('free, 100 calls/day without a key'). These go beyond annotations and are actionable.

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 tight sentences that are front-loaded with the returned shape, then the example, then the cost note. No redundant text; every sentence carries distinct 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?

Output schema exists so return values needn't be explained, and annotations cover safety. The description still covers return fields, ordering, and quota, making it near-complete; minor gap is lack of explicit alternative-tool routing.

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

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

Schema coverage is 100% and already documents the limit param ('Max tags to return (default: all)'). The example('{"limit":10} -> the 10 most-used tags') reinforces the meaning but adds little beyond what the schema states, so baseline 3 applies.

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

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

Uses a specific verb and resource ('Returns every tag') and enumerates the returned fields (count, median annualized revenue, members) plus ordering ('most used first'). This clearly distinguishes it from sibling get_tag (single tag) and list_categories (different resource).

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 example with limit=10 illustrated usage, but no explicit when-to-use/when-not guidance or routing to alternatives like get_tag or list_categories is provided. Usage is implied through the example rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real value: cost model (free, 100 calls/day without a key), default sort behavior (highest revenue first when query is empty), and pagination fields (total, next page). It stops short of saying what confidence tiers or basis values mean, but that 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?

Front-loaded with the trigger sentence and example, with the field list and pagination details compactly packed. Dense but every clause carries information; the enumerated field list is slightly bulky given an output schema exists.

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 7-param search tool with full schema coverage, annotations, and an output schema, the description supplies the trigger, the example, sort defaults, cost limits, and the recommended next call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds semantics the schema lacks, notably default sort order (highest revenue first on empty query), the empty-query-means-all convention, and a worked example with limit. It doesn't explain cursor vs offset precedence, which the schema only partially covers.

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?

Specific verb+resource with an explicit scope statement: it returns AI-agent businesses with sourced, dated revenue, and the title/description both say 'start here'. It clearly separates itself from siblings by naming get_business as the follow-up and list_categories for category slugs.

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?

Opens with an explicit trigger ('Use when the user asks how much revenue, MRR or ARR...or wants real examples of AI businesses in a niche'), then names the next step (get_business {"slug"}) and points to list_categories for slugs. An agent knows both when to call it and what to call afterward.

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, non-destructive and closed-world semantics. The description adds real context beyond that: the shape of each result (lesson + business + themes), the max-50 limit, and a cost/quota model (free, 100 calls/day without a key) that an agent would otherwise not know.

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 dense sentences: capability and filters first, worked example second, cost note last. No filler and the most decision-relevant 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?

An output schema exists, so return values needn't be spelled out, and the description still summarizes result shape and quota. The only gap is pagination behavior — it's unclear whether limit is a hard cap on total results or whether more can be fetched beyond 50.

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 three parameters are already documented, including the enum values and accepted labels. The description's example illustrates how theme and limit combine, which is marginally useful, but adds no format or semantics beyond the schema — 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?

States a specific verb and resource ('Returns builder lessons from every business') plus what each result carries (business and themes). This is clearly distinct from sibling tools like search_businesses or get_business, though it never names those siblings explicitly to confirm the contrast.

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 describes how to narrow results ('filter by query and/or theme') and provides a concrete example call, which implies the intended discovery use case. But with 13 siblings, it gives no explicit when-to-use or when-not guidance versus search_businesses/get_business, leaving the agent to infer routing.

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

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

Annotations already cover read-only, idempotent, and non-destructive, so the bar is lower, and the description adds real value: daily rotation and a free-tier rate limit (100 calls/day without a key). It does not clarify that repeated calls within a day return the same record, which a careful agent might wonder given the 'rotates daily' phrasing.

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 clauses, front-loaded with the return value, then shape, then example, then cost. No wasted text.

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

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

An output schema exists and the description still tells the agent the return shape (same as get_business), plus cost and rotation. Nothing needed to call it correctly is missing.

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

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

Zero parameters, so the baseline is 4. The '{} -> one business record' example reinforces that the call takes no input, which is a small extra confirmation.

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 ('Returns today's featured business') and adds the rotation cadence, so the agent knows exactly what it gets. It notes the profile shape matches get_business, which helps orient it against the sibling without explicitly saying when to prefer that 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 'rotates daily' framing implies when this is useful (a daily spotlight/discovery call), but there is no explicit when-to-use, when-not, or pointer to get_business for a specific record. The 100 calls/day limit is a soft usage hint but not selection 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: results are ordered newest first, each entry carries a source_url, and the call is free at 100 calls/day without a key — a rate-limit disclosure the annotations don't supply. It does not say what happens on an unbounded `since` or whether results are capped by anything other than `limit`.

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

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

Front-loaded with the trigger, then the return shape, then filters, then cost — no filler. The inline JSON example for `since` earns its characters by disambiguating the date format.

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

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

Output schema exists, so return values needn't be spelled out further, and the description still tells the agent the ordering. Combined with annotations and the cost note, an agent has enough to call this correctly; only the meaning of `slug` and any pagination behavior are left implicit.

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 50% schema coverage and no descriptions on `kind` or `slug`, the description does compensate somewhat by naming all four as filters and giving a concrete `since` example. However it never explains what `slug` identifies (a business slug, presumably) and does not map the enum values to the change types with any precision beyond the prose list.

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 — returns the change log of AI startup revenue data, newest first — and names the exact record types (businesses added, figures added/revised/re-dated/removed). No sibling in the list is a changelog tool, so an agent can route to it unambiguously.

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?

"Use when the user asks what is new or what changed recently" gives an explicit trigger condition that maps directly to user phrasing. It stops short of naming when *not* to use it or pointing to an alternative (e.g. vs. leaderboard or get_business for current values), so it misses the 5 bar.

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