nohumans.directory

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 explains the ranking mechanism (verified first, then reputation score, then ascending price), what has_sample means and when to prefer it, and the strict zero-result behavior ('do not invent endpoints'). It also notes recency-weighting of probe success, giving useful context. While it does not state that the operation is read-only, this is fairly implied by 'search' and no mutation is suggested, so the score is a solid 4.

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 longer than ideal but every sentence carries substantive information: ranking, has_sample semantics, usage guidance, and query tips. It is front-loaded with the core purpose, and while it reads as a single dense paragraph, it is not repetitive or wasteful. The structure could be improved with breaks, but the content is dense and purposeful, so it earns a 4 rather than 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?

For a search tool with 5 parameters and no output schema, this description is exceptionally complete. It covers the ranking algorithm, how to interpret result fields (has_sample, status, score), what to do with zero results, how to use the query parameter effectively, and how to prioritize verified services. It addresses both operational behavior and user decision-making, leaving little ambiguity about what to expect.

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 of parameters is 100%, so the baseline is 3. The description adds meaningful value beyond the schema, especially for the query parameter: it emphasizes describing the actual need in your own words, provides examples of specificity, and explains that the exact wording improves the directory over time. It also reinforces the use of min_score (0.8) and how to weight has_sample alongside score, which enriches but does not contradict the schema descriptions.

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 clear, specific statement: 'Search a verified registry of paid (x402) APIs and datasets.' This identifies both the action (search) and the resource (verified registry of paid APIs/datasets), and distinguishes it from the sibling tool get_service_details, which likely retrieves details for a specific service found via this search.

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 explicitly states when to use the tool ('Use this before spending money to find services that actually work') and provides concrete selection criteria ('Prefer results with status verified and score >= 0.8'). It also gives guidance on how to phrase the query and cautions not to invent endpoints if zero results are returned. However, it does not explicitly mention when not to use the tool or an alternative (e.g., get_service_details), so it misses a fully explicit exclusion.

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 provided, so description carries full burden. It describes what information the tool returns but does not disclose side effects, error behavior, authentication requirements, or rate limits. Adequate but minimal added behavioral context.

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 concise sentences: first lists returned fields, second provides usage guidance. No wasted words, front-loaded with purpose.

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 one parameter and no output schema, description adequately covers return fields. Lacks information on error conditions or null returns, but overall provides sufficient context for a simple fetch operation.

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 clear description for the id parameter. The tool description reiterates the origin (from find_paid_service results), adding no new meaning beyond the schema. Baseline score of 3 is appropriate as schema does the heavy lifting.

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?

Description clearly states it fetches full record for one listing by id, listing specific fields returned (endpoint URL, schemas, chains, pricing, reputation). Distinguishes from sibling find_paid_service by referencing its results.

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 advises calling before making a paid request to know request shape and reliability. Provides clear when-to-use context but does not specify when not to use or alternatives beyond the implied sibling.

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