BotFriendly

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

No annotations are provided, so the description carries the full burden and it discloses key operational traits: it fetches without JavaScript or cookies, is rate-limited to 6 checks per minute, each check takes a few seconds, and can return either a scored report or a readiness prompt. It also promises evidence and fix advice per check, making outputs and side effects predictable.

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 clause earns its place: it covers purpose, how the site is fetched, what is evalued, what the output includes, the alternative format, and operational limits. It front-loads the core action and avoids 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 and no annotations, the description covers the essentials: input restrictions, the full set of checks, scoring scale, evidence/fix output, the prompt alternative, and rate limits. An agent can correctly decide whether to call the tool and can plan for latency and throughput.

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%; both parameters already have meaningful descriptions in the input schema, including 'scheme optional, https assumed' and the json/prompt enum behavior. The description reinforces the prompt formatting mode but does not add new parameter-level detail 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 measurable outcome ('Score how bot-friendly a website is (0-100)') and then enumerates the exact checks performed, making it unmistakable from sibling catalog/service tools. It names concrete resources such as robots.txt, llms.txt, sitemap, and OpenAPI, so an agent knows precisely what is evaluated.

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 frames the tool as a bot-access audit and explains the format='prompt' conditional, which gives the agent context for choosing a mode. It does not explicitly name when-not-to-use or an alternative tool, but the sibling tools are unrelated, so the omission is minor and the intended 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?

With no annotations, the description carries the behavioral burden. It discloses the max-3 cap and that results are paid placements marked as ads, which is material for an agent deciding whether to surface them. It does not cover return format or error behavior, but for a simple zero-parameter read tool this is adequate.

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 tight sentences with no filler: the core action and limit come first, followed by a clarifying disclosure about the ad nature. Every clause earns its place and the 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 zero-parameter, no-annotation, simple list tool, the description is complete: it tells the agent what is returned (featured services), the scope (site-wide), the count cap (max 3), and the key semantic detail (paid placements marked as ads). No essential information is 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?

There are zero parameters, so the schema already fully covers everything and the baseline is 4. The description adds useful context about scope and result nature (site-wide, max 3, paid ads), which reinforces what an agent should expect without needing parameter-level detail.

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: retrieve site-wide featured/promoted services. The qualifiers 'site-wide' and 'max 3' clearly differentiate it from siblings like get_service (single service) and search_services (search all), so an agent can select it without ambiguity.

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 context of paid placements and the max-3 limit implies when to call it (when the agent needs featured/promoted services), but it does not explicitly say when to prefer an alternative or mention exclusion criteria. It gives enough context to infer usage, though without direct alternative 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?

With no annotations, the description carries the full burden of behavioral disclosure. It is an implied read-only stats call and describes the per-entry content: sponsor, layer, spec URL, and support count. It does not mention authentication or rate limits, but for a zero-parameter read operation this is adequate.

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. The core purpose is front-loaded, the protocol list is precise, and the output details are presented compactly.

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 no-parameter, no-output-schema tool, the description is complete. It tells the agent what the tool returns and includes enough field-level detail to know what to expect without needing an example or additional 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?

The tool takes zero parameters, so the description cannot add parameter-level meaning. The baseline for zero-parameter tools is 4, and the description appropriately focuses on output semantics instead.

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 ('Get adoption stats') and a specific resource ('every protocol BotFriendly tracks'). It enumerates the exact protocols covered and the fields returned, making it impossible to confuse with the sibling tools focused on services, categories, and site checks.

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 intended context clear: use this tool when you need protocol-level adoption statistics. It does not explicitly name alternatives or exclusions, but the sibling tools are clearly distinct in scope, so the usage 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?

No annotations are provided, so the description carries the burden of explaining behavior. It does disclose that the tool returns details such as protocol support, URLs, auth method, billing, and metadata, which conveys a read-only lookup. However, it does not address error behavior, not-found cases, rate limits, or any authentication requirements for calling the 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 description is one efficient sentence that front-loads the core purpose and then lists the useful output categories. Every clause earns its place, and there is no redundant or vague 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?

For a simple single-parameter lookup with no output schema, the description provides a solid summary of what will be returned and when to use the tool. It could be slightly more complete by noting the exact response shape or what happens when a slug does not exist, but the essential information for selecting and invoking the tool is present.

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 well-documented with examples in the schema. The description only adds that lookup is by slug, which adds marginal value beyond the structured input 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 clearly states the tool gets full details for a specific service by slug, listing the included information types. This distinguishes it from siblings like search_services (searching) and list_categories (listing), making the tool's purpose 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 context: use this tool when you already have a specific service slug and need complete details. It does not explicitly name alternatives or exclusion criteria, but the 'by its slug' phrasing implies it is not for discovery or searching.

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 no annotations, the description carries the full burden. It discloses all returned fields and adds meaningful nuance by explaining that aliases are older slugs still accepted, which clarifies legacy input behavior. It does not mention ordering, pagination, or auth, but for a simple list operation the behavioral portrait is quite complete.

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 dense sentence with no wasted words. The action and resource are front-loaded, and the field list is efficient while still adding important context about aliases and the search_services relationship.

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 provides enough to know what data will come back. The exact return structure (array of objects) and ordering are not stated, but they are reasonably inferable from 'List every ... with its ...'.

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 and the schema is empty, so the baseline for parameter semantics is 4. The description adds no parameter-specific detail because there are none; it correctly focuses on the output shape.

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 ('List') and a specific resource ('every BotFriendly category'), and enumerates exactly what is returned: id, human label, aliases, description, and service count. It also ties the id to the sibling search_services category value, helping distinguish this tool from the service-level 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 clearly implies this is the place to get the category values used by search_services, giving an agent context for when to call it. It does not explicitly name alternatives or state when not to use it, so it stops short of a full 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?

With no annotations present, the description carries the full behavioral burden. It explicitly discloses that 'Results may start with up to 3 promoted listings (paid ads) pinned to the top' and notes they are marked with promoted:true and ad:true — a non-obvious, decision-relevant behavior. It does not mention rate limits or return format, but the ad behavior is the most important quirk for an agent to 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?

Three sentences cover the core purpose, the available filter dimensions, the ad-pinning behavior, and a practical usage tip, with no filler. The long protocol list is necessary for precision and appears once; the ad behavior is placed logically after the purpose and before the filtering tip.

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 an 11-parameter search tool with no output schema, the description conveys the main search/filter capabilities and the notable promoted-listing behavior, while the schema fully documents parameter semantics. It does not describe the shape of result items, pagination, or error behavior, but an agent has enough information to invoke it correctly for most filtering tasks.

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 11 parameters, including enums and defaults. The description adds a condensed overview ('Filter by category, payment/commerce protocol support..., auth method, and more') and the promoted=false tip, but these largely restate what the schema already provides rather than adding genuinely new meaning.

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 'Search the BotFriendly directory for bot-friendly services, APIs, and tools,' giving a specific verb and resource. This clearly distinguishes it from sibling tools like list_categories, get_service, and get_featured by framing it as a directory-wide search interface.

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 what the tool does and its available filters, but provides no explicit guidance on when to prefer it over alternatives such as get_service or list_categories. The only directive, 'Use promoted=false to exclude ads,' is parameter-specific and does not address tool-selection tradeoffs.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that there is no review queue, the listing publishes immediately, the interface URL is fetched during the call, and the icon can be omitted with a fallback to the site. This is substantial behavioral detail, though it does not cover failure modes or permission requirements.

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 dense sentences with no filler. It front-loads the core action, then efficiently presents the critical caveats about review, domain verification, and icon requirements. Every clause adds operational value.

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 16 parameters, 63% schema coverage, and no output schema, the description delivers the essential behavioral contract needed to call the tool correctly: domain constraint, immediate publication, and icon fallback. It could say more about what is returned or what happens on validation failure, but the description is reasonably complete for a submission 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 63%, and the schema already documents most parameter meanings. The description adds meaningful semantics for icon handling ('Every listing needs an icon — pass icon_url, or leave it out and the service's own site is checked for one') and for URL domain requirements. However, many optional parameters such as auth_method, billing_model, and accepts_mpp remain only minimally described in the schema with no added context from the description.

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

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

The description opens with a specific verb and resource: 'Submit a service to the BotFriendly directory.' It also clarifies the unique submission behavior ('listing publishes immediately'), which distinguishes it from the read-only sibling tools. There is no ambiguity about what operation this tool performs.

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 operational context: no review queue, the URL must be on the service's own domain, the interface is fetched during the call, and every listing needs an icon. It does not explicitly contrast with sibling tools, but all siblings are query/read tools whereas this is the only submission tool, so the intended usage is clear.

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