Ready4Bots

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavioral context beyond them: the R0–R3 scoring range, the v0.1 checker version, the explicit limitation that R4 is never awarded and certified is never set, the 'R4 candidate · not verified' hint semantics, and the side effect that a saved report yields a public result URL. This is exactly the kind of constraint disclosure 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?

Four short sentences, all front-loaded with the core action first and constraints after. Each sentence carries information, though the terse score-range jargon ('R0 through R3', 'R4 candidate · not verified') assumes familiarity and could read as cryptic without prior 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?

There is no output schema, so the description must cover return semantics, and it does so reasonably: it names the score range, the never-awarded R4 ceiling, and the public result URL. It stops short of describing the response shape or fields, leaving a small gap for a tool with no structured output contract.

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 one parameter and 100% schema description coverage, the schema already documents the url field ('Public website URL to score'). The description restates the same constraint ('public http(s) URL') without adding format, normalization, or error-handling detail, so it sits at the 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 (Run) and resource (Ready4Bots Bot-Ready check) scoped to a public http(s) URL, and 'The same check the website runs' pins down exactly what the operation is. It is clearly distinguishable from the sibling tools get_business, list_levels, and search_businesses, which handle lookup rather than scoring.

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 ('a public http(s) URL') but never states when to use this versus the sibling lookup tools, nor any when-not conditions. An agent can infer it is the scoring tool for a single URL, but no explicit routing guidance is given.

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 genuine behavioral context beyond that: the returned field set, the explicit exclusion of mystery test data and internal notes, and the certified/unverified-level rule.

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

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

Front-loaded with the core verb/resource and lookup keys, followed by dense, information-bearing sentences about the response. Only slight redundancy between the description's key list and the schema's identical parameter description.

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 carries the return-value burden by naming the response fields and exclusions. Zero required parameters is not addressed (what happens when nothing is supplied), but otherwise the agent has enough 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 schema already tells the agent that 'id' accepts a listing id, slug, domain, or website URL. The description largely restates that, adding no new syntax or format guidance, 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?

States a specific verb and resource ('Fetch one public listing') and enumerates the accepted lookup keys (id, slug, domain, website URL). It distinguishes itself implicitly from search_businesses by being a single-entity lookup, but never names the sibling, 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?

The multiple lookup keys imply 'use this when you already have an identifier' versus search_businesses for discovery, but the routing is left to inference. No explicit when-not or alternative tool is 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine domain behavior beyond that: R4 is a Verified Agent Purchase, the service 'does not place a real order at a third-party shop', the free check caps at R3, and mass tests stop at R3. These are substantive constraints an agent cannot get from 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?

Five short, front-loaded sentences with the primary listing first and semantic detail after; no filler or repetition. The phrasing is somewhat telegraphic ('by three paths'), which costs a little clarity, but every sentence carries 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 zero-param, no-output-schema reference tool, the description should fully explain the returned taxonomy. It defines R4 and states limits on R0-R3, but leaves the meaning of R0 through R3, the R4-N/R4-W seal variants, and the 'three paths' unexplained, so an agent cannot fully interpret the output.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly spends no space on argument semantics and instead documents the enumerated level taxonomy itself.

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 sentence gives a specific verb and resource: 'List Ready4Bots levels R0 through R4, plus seal variants R4-N and R4-W.' It is immediately distinguishable from siblings like check_website and search_businesses. The only weakness is that 'levels' is domain jargon whose meaning must be inferred from later sentences.

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 'use this when' statement or named alternative. Usage is only implied via domain context ('The free check awards R0 through R3 only', 'Mass tests stop at R3'), which hints this is a reference tool for interpreting results produced by the check-related siblings, but the agent must infer that linkage.

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?

Goes well beyond the annotations (readOnly, idempotent, non-destructive). It discloses ranking order (relevance then published R-level), that unverified listings are never certified, that levels appear only when a test recorded one, and a detailed indexSource contract covering the live postgres read and the snapshot/fallbackReason path when the DB is unreachable. This 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-loads the purpose and ranking model before the parameter recap, and most sentences earn their place by describing behavior not visible in structured fields. It runs long and repeats the synonym examples already present in the query parameter, which keeps it from a 5.

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 fully compensates by naming the response envelope (totalIndexed, indexSource) and the per-result fields (level, status, certified, industry, channel, actions, audience, sourceUrl, ready4botsUrl). Combined with the indexSource fallback semantics, an agent has everything needed to call and interpret the 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 ten parameters including the enums and synonyms. The description reiterates the filter surface but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Search the public Ready4Bots index') and immediately scopes what is searched (name, industry, tags, product keywords, category, description, domain). It also distinguishes itself from the sibling get_business by noting they read the same catalog, so an agent can route between search vs 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?

Provides strong context on how results are ranked and enumerates every filterable dimension, which tells the agent when this tool fits. However, it never explicitly contrasts when to use this versus the sibling get_business beyond a single closing sentence, and offers no exclusions or prerequisites.

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?

Goes well beyond the sparse annotations by disclosing state effects: a new report starts in an initial state and does not change ranking or the seal, and a valid Web Bot Auth signature marks the submission verified. It also discloses irreversible data handling (order number truncated to last 4 characters). The undefined term 'offen' (presumably 'open') and the absence of guidance on duplicate submissions keep this from a 5.

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

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

Three sentences, front-loaded with the purpose followed by side-effect and verification details; nothing is padded. Minor deduction because the undefined status word 'offen' forces the reader to guess rather than earning 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 four-required-parameter write tool with no output schema, the description covers side effects, verification, and data minimization, which is what an agent most needs. It omits what happens after submission (confirmation, returned identifier), any rate or duplicate-submission behavior despite idempotentHint=false, and how to amend or remove a report.

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, including the note content stripping and the last-4-characters rule. The description repeats the order-number truncation but adds no format, syntax, or enum guidance beyond the schema, 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?

States a specific verb (submit/write) and resource (a purchase report, problem, or feedback to the Bots Board), and the three report types enumerate the scope. Every sibling tool (check_website, get_business, list_levels, search_businesses) is a read operation, so this write tool is unambiguously distinguishable 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 three report categories implicitly signal when the tool applies, but there is no explicit when-to-use framing, no prerequisites (e.g., is a shop entry required first?), and no alternatives named. Usage is inferable rather than stated.

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