Agent Discovery Board by SarnAI

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

Annotations already declare read-only, idempotent, open-world, non-destructive, so the safety profile is known; the description adds genuinely new behavior: sourced quotations rather than generated answers, no model, the full status enum (answered, partial, not_found, not_available), and cost ('Free'). With no output schema, this return-side disclosure is exactly what the agent needs.

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?

Content is front-loaded and every clause carries information: capability, sourcing, routing, status values, cost. It is written as one dense semicolon-chained sentence, which is harder to scan than separate lines, but nothing is 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 5-parameter tool with no output schema, the description covers capability, sourcing, routing, status enumeration and cost. It stops short of describing what a passage object contains beyond source and link, but the essential contract for calling it correctly 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 description coverage is 100%, so every parameter including limit, product, question, agent_id and trace_id is already documented in the schema. The description adds only indirect hints ('a question naming a listed service' implies scoping) and no format or syntax guidance for the parameters. 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 ('Answers questions about SarnAI's products...') and enumerates the covered products, the sourcing method ('quoting their published documents, each passage with its source and link') and the absence of a model. An agent can distinguish it from describe_listing or find_agents, which are named as follow-ups, without opening either 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?

Gives concrete routing rules: a question naming a listed service returns that listing with describe_listing and how_to_pay 'ready to call', while any other question yields not_found and find_agents. That tells the agent when this tool is the right entry point and what to do next, though it never states an explicit exclusion such as 'do not use for non-SarnAI topics' or when to skip straight to get_listing.

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, it discloses the deterministic inference rule (a rule is added only where every sample satisfies it), the return payload keys, the fail-closed behavior with an error code (template_rejects_sample), and that nothing is stored and the call is free. That is substantive context 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?

Three tight sentences, front-loaded with what is built and from what, followed by the inference rule, the failure mode, and side-effect/cost facts. No filler and nothing repeated from the schema.

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, but the description names the salient return fields (inferred, uncertain, listing_patch) and the failure path, and it states persistence and cost. Combined with the fully described input schema, an agent has enough to invoke 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 description coverage is 100%, so the schema already documents samples, expectations, name, agent_id and trace_id. The description reinforces the sample-count limit and the sample-vs-expectations split but adds no syntax or format detail beyond that; 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?

The description names a specific verb and artifact (builds a verification template), states the input basis (1-10 sample outputs), the mechanism (fixed rules, no model), and the output contents. It is clearly distinguishable from the sibling get_template, which retrieves rather than infers.

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 conveys when this applies: derive a template from samples, use the expectations parameter for what samples cannot show, and expect failure if a sample would be rejected. It does not explicitly name an alternative (e.g. get_template) or say when not to use it, 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?

Annotations already establish read-only, idempotent, closed-world behavior, so the description is free to add real value — and it does: the 404 unknown_listing failure mode, cost ('Free'), and the honesty guarantee that recipe gaps are 'listed, never guessed'. It does not cover rate limits or payload size, but the added context is well beyond the structured fields.

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 promise, then a tight enumerated list of return contents, closing with error and cost. The middle parenthetical about recipes is dense but each clause carries distinct information; nothing is padding.

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 correctly takes on the burden of describing return contents in detail, plus the error case and pricing — everything an agent needs to call it and interpret the result. The only gap is its unresolved relationship to get_listing.

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%, including a concrete UUID example for listing_id, so the schema carries parameter meaning. The description adds nothing about listing_id format or how trace_id continuation interacts with this call, leaving it at the baseline for well-documented schemas.

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 and enumerates exactly what the response contains (connection recipes, payment summary, template flag, trust signals), so an agent knows what it gets. However, it never distinguishes itself from the sibling get_listing, leaving a real ambiguity about which 'fetch one listing' tool to pick.

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 phrase 'Everything needed to use one listing' implies the use case (deciding whether/how to connect to a listing), but there is no explicit when-to-use, no when-not-to-use, and no pointer to get_listing or find_agents as alternatives. 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.

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

Goes well past the readOnly/idempotent annotations: it discloses the default result fields, the ranking, that result.more carries next-page calls, that match_quality "partial" means incomplete coverage, and that total is 0 on partial answers unless total_at_least is set. It also states 'Free, no key', removing auth uncertainty.

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 what it returns and the sources before the parenthetical-dense details. The single long paragraph with heavy semicolon/parenthesis chaining makes it harder to scan than a short bulleted structure would, but almost no sentence is 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 17 parameters and no output schema, the description does the work of explaining the return shape (name, summary, price, health check, connection info, rank) and pagination contract. Only the relationship to sibling search_listings remains unexplained for a definition this complex.

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, but the description adds real semantics: page 1 = ranks 11-35, view "full" returns every field, and mention that price caps or 'no api key' in the need text act as filters. Filter parameters like source and task_category are left to 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?

States a specific verb and resource ('Find AI agents, MCP servers and APIs') plus the concrete sources it aggregates (MCP Registry, x402 Bazaar, Agentic.Market, direct listings). It never clarifies how it relates to the sibling search_listings, so the agent must guess which is the general search entry point.

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?

Gives actionable usage: describe the need in plain words, limit caps at 10, page continues at rank 11, view "full" for every field, and it explicitly routes depth lookups to describe_listing and facets to list_facets. It stops short of stating when to prefer this over search_listings.

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, closed-world and non-destructive, so the bar is lower. The description nevertheless adds real context: a 404 not_found failure mode and the 'Free' cost characteristic, which no structured field conveys.

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 fragments, all front-loaded: retrieval scope first, alternative routing second, failure and cost last. Nothing is padded and every clause carries 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?

No output schema exists, so the description partially compensates by naming the notable returned fields and the 404 case. It does not explain the shape of next_actions or when the trust badge is absent, but for a single-param getter it is nearly sufficient.

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 only parameter is documented as a UUID in-schema. 'By id' in the description adds no format or constraint detail beyond that, 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?

States a specific verb and resource ('One listing's full record by id') plus the extra payload (next_actions, trust-score badge). It is clearly distinguishable from search_listings and describe_listing without reading 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?

Explicitly routes the agent: 'For connection and payment steps use describe_listing,' naming the alternative and the condition that selects it. Combined with 'by id', the split from search_listings is also implied.

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, non-destructive and closed-world, so the safety profile is covered structurally. The description does add genuinely new behavior beyond that: the 404/no_template failure mode, the 'Free' cost signal, and the shape of the returned payload — useful, but thin on what the template's rules and bounds actually govern.

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?

One dense sentence-sentence pair with zero filler, and the resource plus returned fields are front-loaded. The telegraphic style ('404 no_template. Free.') is efficient but occasionally reads as fragments rather than prose.

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 only one required parameter, no output schema, and annotations covering safety, the definition supplies the missing pieces an agent needs: the returned fields, the 404 no_template error, the cost, and the companion tool that constructs the call.

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 listing_id is documented in-schema as a UUID, so the schema does the heavy lifting. The description adds nothing about the parameter (e.g., where a listing_id comes from, as with search_listings) — baseline 3 for full schema coverage.

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?

Names the concrete resource (a listing's verification template) and enumerates what comes back (output_schema, rules and bounds, template_url), which is far more than the title alone. It is distinguishable from build_template and prepare_verification by framing itself as the fetch step, though the verb itself is only implied ('A listing's ... template') rather than stated.

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 positions itself in a workflow by pointing at prepare_verification as the tool that builds the call, and ties the result to the 'Agent Output Verifier'. That is implied usage rather than explicit when-to-use / when-not guidance, and it never states why an agent would call this directly instead of build_template.

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=true, idempotent, non-destructive and open-world, so safety needs little restating. The description still adds real value: it confirms "never pays" (no transaction is produced) and discloses an output convention — steps the backend cannot state are flagged documented: false — plus that the call is free.

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 what it returns, then the optional modifiers, then the scope disclaimer "Explains only; never pays. Free." Despite dense punctuation, no sentence is 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 five optional parameters, no output schema and no required inputs, the description does the work of describing the response shape (steps, cost with amount/asset/network and USD for recognised stablecoins, call recipe, documented:false markers). Only the trace_id continuation flow and the listing_id-vs-target exclusivity are left entirely to the 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?

Schema description coverage is 100%, so every parameter including the nested Payer object is already documented, and the baseline is 3. The description reinforces payer as the cheapest-usable-option selector and expands target='verifier' to include the AI Agent Scores lookup price, but most of that meaning already lives in 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?

"How one listing is paid for and what it costs" plus the enumerated contents (steps per payment type, cost, call recipe) makes the resource and the returned information concrete, and "Explains only; never pays" separates it from action tools like prepare_verification. It does not name a sibling explicitly, so an agent must infer the boundary with describe_listing/get_listing.

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?

Useful conditional guidance is given for two inputs ("With payer, the cheapest option you can use", "target 'verifier' gives the Agent Output Verifier's price and free paths"). However, there is no when-to-use/when-not-to-use statement relative to siblings such as prepare_verification or describe_listing, so routing is only implied.

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, non-destructive and non-open-world, so the safety profile is covered. The description adds only the 'Free' note (no cost/credit), which is genuinely useful but unexplained; it says nothing about whether counts are computed over all matches regardless of page size or about caching.

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 front-loaded sentence plus a one-word cost note; no filler. The facet enumeration is long but each item is load-bearing because it defines the response keys.

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 16 optional parameters and no output schema, the description should sketch the return shape more explicitly (per-facet buckets with counts) and note that results are unpaginated aggregates. The filter-sharing clause plus the facet list gets an agent most of the way there, but the return contract remains 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?

Schema description coverage is 100% and every parameter carries a description (mostly 'As in search_listings'), so the schema does the heavy lifting. The description's only added parameter information is that 'q' is included among the shared filters, which is not enough to exceed 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 (counts) and resource (matching listings) and enumerates the six facet dimensions it returns: task category, listing type, payment network, source, connection type, payment type. It is clearly distinguishable from search_listings and the other siblings, though the framing is slightly dense.

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?

Implies usage by tying filters to 'the same filters as search_listings (including q)', so an agent can infer it is a companion aggregation call. But it never says when to call this instead of, or before, search_listings, nor that it ignores pagination.

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 annotations covering readOnly, idempotent, openWorld and non-destructive behavior, the description adds that it never evaluates or sends anything, that it reads the verifier's live documents, and that it is free. These are useful behavioral details beyond the annotations and do not contradict them.

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 first sentence is a run-on packing preparation, request_body, free paths, paid path, and live documents into one clause, making it hard to parse. The later sentences are short and useful, but the overall structure is not cleanly 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 an 8-parameter tool with nested objects and no output schema, the description leaves ambiguity about what exactly is returned (request_body plus send instructions?) and how the free vs paid paths are represented. It covers the basics but does not fully explain the output or flow.

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 parameters are already documented. The description restates that you can give listing_id (its template) or an inline output_schema, which is already in the schema, and does not add new meaning beyond that 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?

The description states a specific verb 'Prepares' and resource 'call to the Agent Output Verifier for one output', and distinguishes from the verifier itself by noting 'It never evaluates or sends anything.' However, the run-on phrase about sending with free paths and the paid path slightly muddies the core purpose.

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 a preparation step before sending to the verifier and notes it is 'Free', but gives no explicit when-to-use vs alternatives or exclusions. The choice between listing_id and output_schema is mentioned, but that is parameter-level guidance rather than usage context.

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?

Given only coarse annotations, the description carries real behavioral weight: it explains that omitting submit yields a dry-run that reports what would be stored and what is missing, that submit: true persists immediately, that indexing typically completes in seconds, and it points at GET /listings/{id}/status for tracking. It also discloses the no-auth/no-wallet posture. This is exactly the added context the annotations do not provide.

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 plus one example; the free/no-account hook is front-loaded, mode behaviour follows, and the example is compact and illustrative rather than redundant. No 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 22-parameter, no-output-schema registration tool, the description covers the essential decision (check vs save), the post-save lifecycle, and a worked example. It stops short of addressing how the optional trust/verification and pricing fields interact with the check output, but the rich schema fills that gap.

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 baseline is 3; the description rises above it by explaining the semantics of submit (validation vs persistence) and by giving a concrete example payload using name, description, endpoint_url and submit. The 21 other optional parameters (pricing, verification, expectations, connections) are left entirely to 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?

States a concrete verb and resource ('List your own AI agent (A2A), MCP server or x402 API here') and immediately clarifies the two modes it supports. It does not explicitly differentiate itself from near neighbours like build_template, prepare_verification or describe_listing, so an agent must infer the boundary.

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?

Clearly frames the use case: free, no wallet, no account, and explains the choice between a check-only call and submit: true. It lacks any exclusion guidance — nothing says when to prefer prepare_verification or build_template instead, or what to do if the listing already exists (annotation says not idempotent).

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 annotations, the description discloses ranking behavior, fuzzy fallback, hidden test listings, pagination scope, self-reported data, badge lookup semantics, import claimed status, and cost. These are substantial behavioral details an agent needs before invoking 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 front-loaded with purpose and alternative routing, then covers important behavior in dense clauses. It is appropriately sized for a 20-parameter search tool, though the telegraphic semicolon style could be slightly clearer.

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 complex search tool with no output schema, the description explains result ordering, compact versus full records, trust-score badge behavior, pagination, hidden test listings, and import metadata. These details are sufficient for an agent to interpret and page through results 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%, so the baseline is 3, but the description adds meaning for key parameters: q affects relevance and fuzzy fallback, compact controls record shape, include_test controls hidden test listings, cursor belongs to its exact query, and source/claimed relate to imports. It does not clarify every one of the 20 parameters, but it meaningfully supplements 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: browse and filter the directory as raw records. It explicitly distinguishes this from the sibling find_agents for plain-words needs, so an agent can select between them 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?

It clearly routes plain-words searches to find_agents and explains q-based ordering versus recency-based browsing. It does not cover when to prefer other siblings like get_listing or list_facets, so the guidance is strong but not exhaustive.

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