afro.tools

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

Annotations only declare a safe read; the description goes far beyond by decoding the status taxonomy (verified/deprecated/other), explaining that sandbox verification does not prove production behaviour, and mandating a user warning when status is not 'verified'. It also predicts error shapes (isError with available_capabilities, did_you_mean, removed_in) and the _mcp_size_note truncation hint — behavior an agent could not infer 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?

Front-loaded with the core action and its result, then organized as a field-by-field key, which is scannable despite its length. It is longer than typical, but nearly every line is a disambiguation rule for a returned field an agent must interpret; only the trailing error-handling sentence overlaps slightly with the Returns section.

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?

No output schema exists, so the description carries the full burden of explaining the response — and it does, covering status, verification, open_questions, environments, auth blocks, parameters vs input_schema, success_condition, and error cases. For a read-only lookup tool with three simple params, nothing an agent needs to call or interpret it 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 already 100%, so baseline is 3; the description earns extra by explaining what variant actually does — filtering oneOf/union branches by discriminator value, leaving unmatched unions whole, and surfacing the result under 'variants'. It also clarifies that a path parameter fills {name} in endpoint.url. The provider/capability params get no added syntax guidance beyond the schema examples.

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 first sentence states a specific verb and resource — 'Returns the full spec payload for a provider + capability' — plus what is inside (canonical_example.ts source). An agent knows exactly what it gets and can distinguish it from search_specs (discovery) and list_providers (enumeration).

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 explicit timing — 'before writing API calls' — and names the prerequisites: 'Use search_specs or list_providers first to discover available providers and capabilities.' It also states what to do on failure (pick from available_capabilities, use did_you_mean), which routes the agent rather than leaving it to guess.

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 safety needs no restating. The description adds real semantics annotations cannot convey: what all_verified means precisely (true only when ALL capabilities are verified) and the caveat that specs can still contain errors because untested capabilities exist.

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 core statement is front-loaded and the caveat/follow-up logic is ordered sensibly. It is slightly repetitive — the all_verified false case is restated in both the second and third paragraphs — but the extra lines still carry distinct information about untested capabilities.

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 it does so with an explicit object shape and all top-level field names. It stops short of explaining fields like channels or docs_public, which leaves some interpretation to the agent.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly spends no words on inputs.

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

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

The opening sentence gives a specific verb and resource ("Lists all providers") plus the salient attribute (verification status). It implicitly separates itself from search_specs/get_spec by being the enumerate-everything entry point, though it never explicitly says "use this to discover providers, use search_specs to filter."

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 follow-up routing: when all_verified is false, "call search_specs or get_spec and check each capability's status." That is a genuine use-vs-alternative instruction, though it describes the drill-down path rather than when to pick this tool over search_specs in the first place.

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?

Although readOnlyHint/idempotentHint already signal safety, the description adds what the annotations cannot: "Nothing is posted: the user reviews the text and submits it on GitHub" — clarifying the human handoff. It also documents the failure mode ("If a spec does not exist: isError, with { error, available_capabilities }") and instructs on what to do with the returned url/next_step.

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 key behavior (build a link, nothing is posted) is front-loaded, then usage conditions, then parameters, then return shape — a sensible ordering. A few Args lines duplicate schema text verbatim (e.g. tested_on format), slightly diluting density.

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

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

For a tool with no output schema, the description fully covers the return contract ({ url, next_step } and the error shape with available_capabilities) as well as the agent's required follow-through. Nothing needed to invoke it correctly is absent.

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 earns a bump by supplying concrete examples for provider slug, capability objects, and result strings ("wrong: status is SUCCESSFUL, spec says succeeded"), plus an explicit PII/secret prohibition on details. The Args block largely restates the schema, so it is not a full 5.

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 artifact: "Builds a pre-filled GitHub link to report how an integration went against a spec". This is clearly distinct from the sibling tools (get_spec, request_spec, search_specs), which retrieve or request specs rather than file verification reports.

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 states exactly when to call: "when the user confirms an integration works against the real API (sandbox or production), or when you find the spec does not match the API". It also adds a scoping rule: "One report per provider, covering every capability of the flow... each one is verified on its own", which prevents the agent from splitting reports per capability.

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 by disclosing the external side effect (maintainers are notified), the exact return shapes, and that a missing count must not be guessed to the user. It also specifies error behavior — an isError means the request was NOT recorded and the user must be told — which the openWorldHint/idempotentHint flags alone never convey. Nothing contradicts the annotations: logging a request is a non-read-only, non-idempotent, non-destructive write.

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 purpose and the selection condition, then cleanly separated Args and Returns blocks. The longer Returns section earns its space because there is no output schema and the count-absent and isError branches require explicit agent behavior.

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 return contract itself and does so completely: success with optional count, the already-exists case, and the storage-failure case each map to a specific agent response. Combined with the caller precondition, nothing needed to invoke or report results 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% and the description's argument notes only repeat the schema's example values for provider and capability. The one useful addition is that the pair is treated as an exact key used for all-time counting, but that is stated in the Returns section rather than as parameter guidance. Baseline 3 is appropriate.

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

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

States a specific verb and resource — logs a spec request and notifies maintainers — plus the exact precondition (no spec exists in the registry). The reference to list_providers and the scoping to a provider+capability pair separates it cleanly from get_spec and search_specs.

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 when to call it: a user asks for a provider or capability with no spec, and tells the agent to check list_providers first. It also covers the negative case indirectly by documenting the { logged: false } return when the spec already exists. It doesn't mention search_specs as an alternative route, so it falls just short of full when/when-not coverage.

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 a safe idempotent read, and the description adds substantive context beyond them: what is deliberately excluded from results, the meaning of each status value with the strong 'not tested against live API, may contain errors' caveat, and the semantics of note, hint, unverified_count and warning in the response.

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?

Purpose is front-loaded and the Args/Returns structure is scannable, with almost every sentence carrying operational information. It is on the long side and repeats some return-shape detail, but nothing is filler-grade.

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?

No output schema exists, and the description fully documents the return object, its optional fields, and the interpretation rules for status — everything needed to call and interpret results for an 8-parameter, zero-required search 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?

With only 50% schema coverage, the description compensates thoroughly: query is explained as all-words-must-match across named fields with provider ranking, category carries examples plus the legacy 'sms' alias and a discovery path via list_providers, and every other filter gets a concrete value example or definition. This clearly exceeds what the bare 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?

Opens with a specific verb and resource ('Searches specs') plus the exact filter dimensions, and explicitly scopes what is omitted (no endpoints, schemas, gotchas, canonical_example) with a pointer to get_spec for the full payload. An agent can distinguish this from get_spec and list_providers 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?

Names the alternative explicitly ('Use get_spec with the exact capability name to retrieve the full payload') and gives the condition for it, plus how to handle variants via get_spec "variant". It also tells the agent to check the status field and inform the user when a spec is not verified, and the hint field tells it to widen the search rather than declare a provider unavailable.

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