Agent Discovery Board by SarnAI

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

Beyond the annotations (which only declare it a safe, idempotent, closed-world read), the description discloses substantial behavior: outputs are verbatim quotes, 'no model writes anything', a four-value status taxonomy is never guessed, results are deterministic, and it is free with no payment or account required. This is exactly the extra 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?

Single front-loaded paragraph that leads with what the tool does and then piles on return and status detail. Dense but every clause carries information; the inline status enumeration makes it slightly heavy to scan, keeping it short of 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 correctly shoulders the return-value burden by describing quoted passages with source/section/link plus the set of status outcomes. It omits the conversational continuation behavior of trace_id, but that is covered by the schema, so the gap is minor.

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 question, limit, product, agent_id and trace_id are all already documented (including the product enum mapping to board/verifier/scores). The description adds no syntax or semantics beyond the schema and never mentions the trace_id conversation-continuation parameter, 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?

The description names a specific verb (answers a question) and a tightly bounded resource corpus (SarnAI's published documents for the Agent Discovery Board, Agent Output Verifier, and Agent Scores), and specifies the output form (verbatim passages with source, section and link). This is clearly distinguishable from siblings like find_agents or search_listings, which operate over live agent/listing data rather than product documentation.

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?

Usage is implied rather than stated: the tool is for questions about the three named products. It adds useful signal about question types ('what is' gets the defining passage first; price/free-path questions get a direct answer), but never says when to prefer this over sibling tools like how_to_pay or get_listing, nor any exclusions.

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 the notes that it 'Stores nothing' and is 'Deterministic' largely reinforce what is structured. The description goes further, though, and discloses genuinely non-structured behavior: the failure contract (template_rejects_sample rather than returning a bad template), the no-model inference rules, and 'free, no payment or account required'.

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?

It is dense but front-loaded: the core action and mechanism come first, then inference rules, then return/behavior guarantees. Each sentence carries information (returns, failure mode, storage, determinism, cost) with little duplication, though the single-block length is heavy for a 5-parameter tool.

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 explaining returns and does so ('inferred', 'uncertain', 'listing_patch'), plus the failure mode and stateless/deterministic guarantees. It stops short of explaining what the agent should do with the `listing_patch` or how it relates to prepare_verification/get_template, leaving a small next-step 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 3 is the baseline. The description adds real meaning beyond the schema for `samples` ('more varied samples teach it which fields are optional') and explains how input drives inference and the bounds/rule derivation, which the schema alone does not convey.

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 ('Builds a verification template ... from one to ten sample outputs') and discloses the mechanism ('a fixed procedure (no model)'), so the agent knows exactly what the tool produces. It does not explicitly differentiate itself from the sibling get_template or prepare_verification, which keeps it 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?

Usage is implied rather than stated: the agent must infer that this is the tool to call when it has sample outputs and needs a template built. There is no explicit 'use this instead of X' or when-not guidance against get_template/prepare_verification, and no prerequisites beyond 'one to ten samples'.

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 cover readOnly, idempotent and non-destructive, so the bar is lower, and the description still adds real value: deterministic output, free/no account or payment required, a documented 404 unknown_listing failure mode, and the 'listed, never guessed' guarantee about undocumented fields. Minor gap: no pagination/size or latency expectations.

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 lead clause 'Everything needed to use one listing' is front-loaded and the closing sentences are crisp, but the core sentence is a long run-on with nested parentheticals that packs its enumeration densely enough to be hard to scan.

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 100% schema coverage on inputs, the description carries the return-value burden and does so thoroughly, including error behavior. It is nearly complete for this tool's complexity; only the absence of any sibling disambiguation keeps it from a 5.

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 listing_id, agent_id and trace_id are already fully documented in the schema. The description adds no format, constraint, or interaction detail beyond what is there, which is the expected baseline when the 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?

The description enumerates exactly what the tool returns for a single listing: ordered how_to_connect steps with call recipes, payment summary, verification template presence, and trust signals. That is a specific resource and scope. It stops short of 5 because it never contrasts itself with the close sibling get_listing or find_agents, so the 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?

Usage is implied ('Everything needed to use one listing', id from find_agents) rather than stated. There is no explicit when-to-use versus get_listing/search_listings, and no stated preconditions, so the agent gets only a weak routing signal.

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: deterministic, free with no payment or account, stale listings hidden unless include_stale, ordering rules (name/opening matches first, templated+passing-probe services first for verification needs), and the presence of interpretation, relaxations and next_actions. It does not document return shape or pagination beyond 'up to limit compact matches'.

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 and the need/filters mechanism are front-loaded, then output behavior and constraints follow in compact order. It is dense but nearly every clause carries information; minor redundancy between the need clause and the schema's need 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?

For a 13-parameter, no-output-schema tool with all-optional inputs, the description explains the main output artifacts (compact matches, next_actions, interpretation, relaxations) and the key filtering behavior. It leaves some filter parameters (network, source, agent_id) to the schema, which is acceptable.

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 meaning: how fixed rules turn connection, payment, price and task words into filters, that interpretation shows which, and what relaxations reports. It also clarifies the include_stale and limit defaults from the tool's perspective.

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 a specific verb and resource — finds services on the Agent Discovery Board — and scopes it to a need expressed in plain words or filters. It does not explicitly distinguish itself from the sibling search_listings, which is the one plausible alternative, 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?

Gives useful operating context (put the need in plain words and/or use filters, omit trace_id on the first call and reuse it to continue a conversation), which implies usage. But it never states when to pick this over search_listings or list_facets, and there are no exclusions.

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 read-only, idempotent, non-destructive, closed-world behavior, but the description adds cost/auth context ('Free, no payment or account required'), error semantics ('404 not_found if the id does not exist'), and hints at payload contents (next_actions, live trust-score badge). It does not mention rate limits or pagination, which is a minor gap given a single-record fetch.

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 scope, then the alternative, error case, and cost in descending priority. Three short sentences with no real waste, though the trust-score badge detail is slightly decorative relative to the rest.

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 appropriately sketches the return shape (full record, next_actions, badge) and covers the failure mode and access cost. An agent has enough to call it correctly; only edge behaviors like very large records are unaddressed.

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?

Only one parameter and the schema already documents it fully at 100% coverage (UUID, sourced from search_listings). The description adds no format or syntax detail beyond what the schema states, 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 ('Fetch one listing by id') and pins the exact underlying operation ('the full record GET /listings/{id} returns'). It explicitly contrasts itself with the sibling describe_listing, so an agent can route 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?

Names the alternative tool and the exact condition that selects it: 'For connection steps and payment steps in one place use describe_listing.' The schema also points to search_listings as the source of ids, closing the discovery loop.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds behavior annotations don't carry: a specific failure mode (404 no_template when the listing has none) and an access/cost condition ('Free, no payment or account required'). That is meaningful added 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?

Three tight sentences, front-loaded with what the tool returns, then usage, then error/cost. The field enumeration is dense but each clause carries information an agent needs; nothing is wasted.

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 usefully characterizes the return payload (output_schema, verification rules/bounds/enforce_rules, template_url). Combined with the error case and free-access note, it covers what an agent needs to call and interpret this 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?

Only one parameter with 100% schema coverage; the schema already explains listing_id is a UUID obtainable from search_listings. The description adds no format or sourcing detail beyond that, 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 resource ('a listing's verification template') and enumerates its contents (output_schema, rules, bounds, enforce_rules, template_url), so an agent knows exactly what it retrieves. It also implicitly separates itself from siblings like build_template and prepare_verification by describing the read-only retrieval role.

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: 'Use it with the Agent Output Verifier (prepare_verification builds the call),' naming the complementary sibling and its role. It lacks a stated when-not condition, but the pairing guidance is clear enough for correct selection.

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/non-destructive annotations, it discloses that the call is deterministic, free, requires no payment or account, and that missing steps are explicitly flagged ('documented: false'). That adds auth-needs, cost, and output-honesty context the annotations do not 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?

The purpose is front-loaded and every clause carries signal (payment types, cost fields, payer behavior, call recipe, constraints). It is dense and parenthetical-heavy in places, but for a complex pricing tool the length is justified and non-redundant.

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 still sketches the return shape (per-type ordered steps, cost amount/asset/network/USD, call recipe, documented flags) and covers the free/paid and determinism constraints. An agent has enough to decide when and how 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%, so baseline is 3, but the description adds real semantic value: it explains that 'payer' is used to select 'the cheapest option you can use' and that 'target: verifier' switches to the verifier's own price/free paths. It largely repeats the object shape already in the schema, keeping it just above baseline rather than at 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 resource ('How a listing is paid for, step by step, and what it costs'), enumerates the payment types returned, and explicitly contrasts itself with a payment action ('It only explains; it never pays'). An agent can distinguish this explanation tool from sibling readers like get_listing or describe_listing 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?

It gives clear invocation context ('Give listing_id, or target 'verifier' for the Agent Output Verifier's live price') and states the tool requires no payment or account. However, it never names or routes to sibling tools (e.g. get_listing for raw listing data), so the when-to-use picture is clear but not fully disambiguated from alternatives.

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 the safety profile is covered. The description still adds value beyond them: 'Not paginated', the special bucket semantics for no_connection_declared / no_payment_declared, and 'Free, no payment or account required' — none of which appear in 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?

Dense but front-loaded: what it counts first, then when to use it, then behavioral notes. The dimension list is long but each item is load-bearing; a slightly run-on first sentence keeps it just short of ideal.

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 14-parameter, zero-required, non-paginated aggregation tool with no output schema, the description covers purpose, filter parity with search_listings, pagination behavior, and cost/auth requirements. The only gap is that the returned count shape (per-dimension buckets) is only implied rather than stated.

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 adds meaning the schema does not: it enumerates which dimensions are faceted and explains the special 'none' buckets (no_connection_declared / no_payment_declared), which are not present in the schema's enum lists.

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 a specific verb ('Counts of matching listings') plus the exact facet dimensions it groups by (task_category, listing_type, payment network, import source, connection type, payment type), and ties its filter set to search_listings (including q). An agent can immediately tell this apart from search_listings: same filters, aggregated counts instead of listing rows.

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?

'Use it to see what exists before narrowing a search' gives a concrete when-to-use and implicitly routes the agent to search_listings for the actual result set. It lacks an explicit when-not-to-use or a named alternative clause, but the pairing with search_listings 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?

Annotations already cover read-only/idempotent/destructive/openWorld, and the description adds genuinely new context: it never sends the request, evaluates nothing itself, is deterministic, and requires no payment or account. It stops short of describing the shape or limits of the returned `send` structure.

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 piece is compact, with each clause carrying information about inputs or outputs. The middle sentence is dense and slightly tangled ('with the free paths (MCP, and REST when the verifier says so) and the paid path'), which costs a little readability.

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 7 parameters, the description usefully sketches the return payload (`request_body` filled once, plus `send`), which annotations cannot convey. Remaining gaps (trace_id continuation, task_id/agent_id roles, `send` structure) are covered by the schema, so an agent has nearly everything needed.

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 7 parameters, including the listing_id/output_schema exclusivity. The description only restates that either listing_id or an inline output_schema is given, adding no syntax, format, or trace-continuation detail beyond 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 names a specific verb+resource ('Prepares the exact call to the Agent Output Verifier for one output') and enumerates what is produced (`request_body` and `send` with free/paid paths). It is clearly not the verifier itself, but it never names a sibling tool as the alternative, so the differentiation from the rest of the toolset is left implicit.

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 a real selection rule for the inputs ('Give listing_id (its template) or an inline output_schema') and states it 'never sends the request', implying a prepare-then-send workflow. However, it never says when to prefer this over a tool that actually sends or evaluates, and offers no explicit when-not 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?

Goes well beyond the annotations: it discloses that validation runs the same checks and per-client limit as POST /listings, that new listings rank after probed ones until a health probe passes, that later edits are wallet-signed, and that the operation is free with no account. These are non-obvious behavioral traits an agent could not infer from readOnlyHint=false, destructiveHint=false, idempotentHint=false, or openWorldHint=true.

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, then the validate-by-default behavior, then the submit path and side effects, so an agent can stop reading once it has what it needs. Dense but nearly every sentence carries distinct information; a small amount of return-field detail could be trimmed.

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 22 parameters, no required fields, and no output schema, the description does the heavy lifting of explaining the default validation response and the create path. It leaves most of the 22 parameters to the schema, but since coverage there is complete, nothing an agent needs to call correctly 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 description coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: submit's default-vs-create semantics and the same-checks/per-client-limit equivalence to POST /listings. It also explains the validation reply fields (errors with fixes, normalized_listing, missing_value, claim_instead), which is more than the parameters themselves.

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: listing a service on the Agent Discovery Board, plus the alternate mode of finding an existing listing to claim. The dual intent (validate vs. create) is clear, but no sibling tool is named, so the distinction from build_template or search_listings is left implicit.

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?

Explains the default posture (validate-only) and the exact switch that changes it (submit: true), and notes that claim_instead tells you when the endpoint is already listed. It gives clear context but doesn't explicitly name alternative tools or say when not to use this one.

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 cover read-only/idempotent/no-open-world, so the description goes well beyond them: results are unvetted submitter claims, badge is a live trust lookup where null is not bad, failed/never-probed/orphaned listings rank last but are never hidden, and stale_reason is defined. It also discloses the error contract (isError with error_code and next_actions).

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 resource before the detail, and nearly every clause carries distinct information. It is a dense single paragraph that borders on overload for an 18-parameter tool, but little of it is redundant.

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 18 parameters, this description carries the full burden, and it does: it enumerates the compact return fields, describes the full-record expansion, explains ordering and paging, and covers the error shape. Nothing an agent needs to call it correctly 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%, so the baseline is 3, but the description adds cross-cutting semantics the schema lacks: q switches ordering to full-text relevance with a typo-tolerant fuzzy fallback, max_price matches only recognised stablecoins, a cursor is bound to its exact query, and all filters combine with q.

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 (searches and browses) plus the exact resource (the Agent Discovery Board) and what it contains. It explicitly names sibling tools (find_agents, get_listing, list_facets, get_template) so an agent can route without opening other 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?

Explicitly routes plain-words needs to find_agents and points to get_listing/list_facets/get_template for adjacent tasks. It also states what it costs (free, no payment or account required) and how filters combine with q, leaving little to inference.

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