Agent Discovery Board

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

Annotations cover the safety profile (readOnly, idempotent, closed-world), and the description adds substantial non-obvious behavior: verbatim-only quotations, no model generation, deterministic output, the four status values with their exact meanings, unreadable-source warnings and stale-copy marking, and no payment/account needed.

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 purpose and the source-document list, then behavior and status semantics. It is a dense paragraph and slightly overlong, but nearly every clause carries actionable information rather than restating structured fields.

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 must describe the return shape, and it does: status enum values, interpretation, product scoping, warnings and freshness markers. Nothing an agent needs to call or interpret this tool 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 goes further by explaining `product` as a search restriction and by naming response-side concepts (`interpretation`, `warnings`, last-read timestamps) that have no output schema to carry them.

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 (answers a question) and resource (Sarnai's published documents for the Board, Verifier and Scores), and enumerates exactly which source documents are searched. An agent can distinguish this from siblings like find_agents or search_listings without opening any 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?

Usage context is clear: ask plain-word questions about the three products' published docs, optionally narrowed via `product`. It doesn't explicitly name alternatives or state when NOT to use it, but the routing is unambiguous given the sibling set.

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?

Adds substantial context beyond the annotations: no model is used (fixed procedure), the operation is deterministic and stores nothing, it is free with no account, and crucially it fails with template_rejects_sample rather than returning a template that would reject the samples. This is exactly the kind of behavioral disclosure annotations cannot convey.

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 purpose, then detail in a logical order (inputs, expectations, response, guarantees). It is a dense single block with minor redundancy ('no model' / 'Deterministic' / 'Stores nothing' cluster), but every sentence carries usable 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 correctly carries the return burden, naming `inferred`, `uncertain`, and `listing_patch`, plus the rejection failure mode. One small gap: all parameters are optional yet the text says 'from one to ten sample outputs', leaving the zero-sample case 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?

Schema description coverage is 100%, so the baseline is 3; the description adds value by explaining the inference logic (types/required/formats come from what every sample contains; rules added only where all samples satisfy them; more varied samples reveal optionality). It does not clarify the null/default behavior of `samples` or `trace_id` 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?

States a concrete verb and artifact: 'Builds a verification template - a JSON Schema plus cross-field rules and bounds - from one to ten sample outputs.' It further specifies the inference procedure and differentiates itself from siblings like get_template and prepare_verification by describing exactly what is produced (inferred/uncertain/listing_patch).

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 clear context for use: feed 1-10 sample outputs, and use `expectations` for things samples cannot show. However, it never explicitly states when to choose this over siblings such as get_template or prepare_verification, leaving the routing decision partly to inference.

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 safety profile is covered. The description adds genuinely non-redundant behavior: a deterministic response, an explicit 404 unknown_listing error for a bad id, and that no payment or account is needed.

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 value proposition, followed by a dense but purposeful enumeration of returned content and two short sentences on error/determinism/cost. No filler, though the middle clause is a long parenthetical list that a reader must parse carefully.

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 correctly carries the burden of describing return values, and it does so thoroughly (connection steps, payment summary, verification rule count, trust signals, warnings). Error behavior, determinism and cost are also covered, leaving only pagination/filtering depth unaddressed, which is not applicable here.

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 listing_id, agent_id and trace_id are all documented in the schema itself (including the 'UUID, e.g. from find_agents' hint). The description adds only the indirect point that a missing id yields 404; with the schema doing the heavy lifting, 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 clear verb and resource (describe one listing) and enumerates exactly what it returns: how_to_connect steps, payment summary, verification template, trust signals, and warnings. It is specific enough to be actionable, but it never distinguishes itself from the similarly named sibling get_listing, leaving the agent to infer the difference.

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?

'Everything an agent needs to use one listing, in one call' implies the usage context (call this when you need to actually consume a listing), and 'Free, no payment or account required' removes a potential gating concern. However, no when-not condition or named alternative (e.g. get_listing vs describe_listing) is given, so routing is left to inference.

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 readOnly/idempotent annotations: it discloses determinism (no model involved, same input gives same answer), that stale listings are hidden unless include_stale is set, that interpretation/relaxations are returned, and that the call is free with no payment or account required. This is exactly the extra behavioral 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?

Purpose is front-loaded in the first sentence, followed by usage, output shape, and constraints in a logical order, with no filler. It is a dense single block rather than segmented, but every sentence carries information an agent needs.

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

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

For an 11-parameter tool with no output schema, the description covers the gaps: it enumerates the returned fields (id, name, price, connection/payment types, verifiability, stale/unclaimed), describes the interpretation and relaxations outputs, and points to follow-up tools (describe_listing, how_to_pay). Nothing essential for correct invocation 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: it explains that words for connection type, payment type, price cap and task are converted into filters by fixed rules and that the response's interpretation shows which rules fired and what was ignored. That mapping between free-text `need` and the filter parameters is not derivable from the schema alone.

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 ('Finds services on the Agent Discovery Board') plus the scope ('that can do what you need'), so an agent immediately knows this is a natural-language discovery entry point. It stops short of explicitly contrasting itself with the sibling search_listings/list_facets tools, so it is clear but not fully differentiated.

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 tells the agent how to invoke it ('Say it in plain words in `need` ... and/or give explicit filters') and when the relaxation output becomes relevant ('when little or nothing matches'). It gives clear context but names no alternative tool for exact/faceted lookups, so there are no explicit when-not-to-use 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 cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: it discloses the next_actions payload the caller gets back, the live trust-score badge, the 404 not_found failure mode, and that no payment or account is needed. It doesn't cover pagination or auth, but for a single-record read that is minor.

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 in the first clause, then progressive detail on returned fields and error behavior. Dense but every clause carries information; the embedded REST-endpoint reference and next_actions explanation are the slight heavy spots.

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 it does describe next_actions and the trust-score badge plus the 404 error path. It is close to complete for a one-parameter read tool; only return shape details (full field list) are left unspecified.

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 the single parameter (UUID listing_id) is fully documented in the schema, including where to source it. The description adds only 'by id', so the 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 ('Fetch one listing by id') and pins it to the equivalent REST endpoint GET /listings/{id}, so the agent knows exactly what it retrieves. It does not name the close sibling alternatives (search_listings, describe_listing) to differentiate, capping it below 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 by the 'by id' framing and the schema's note that ids come from search_listings, but the description never states when to use this instead of search_listings or describe_listing, nor any preconditions beyond an id being available. It adds the useful 'free, no payment or account required' constraint but no 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 cover readOnly/idempotent/non-destructive. The description adds meaningfully beyond them: two distinct 404 outcomes (no_template vs not_found) and that the call is free with no payment or account required. It does not describe response size or caching, but the added error/auth context is solid.

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 resource, then supporting detail about usage and error codes. The single long sentence with nested parentheses is dense but every clause earns its place; a small readability cost keeps it from 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?

Despite no output schema, the description enumerates the return payload (output_schema plus optional verification and template_url), so an agent knows what to expect. Together with the error codes and auth-free note, nothing essential for correct invocation 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% with a single required parameter, so the schema already documents listing_id as a UUID from search_listings. The description adds no format or syntax detail beyond that, which is the expected baseline when the schema does the work.

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+resource ('get a listing's full verification template') and enumerates the returned fields (output_schema, verification, template_url). It does not explicitly contrast with the sibling build_template or get_listing, so it falls short of full sibling differentiation.

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?

Says it is most useful for a verification_profile listing but available on any listing with one, and directs the agent to pair it with the sibling verification service's POST /verify/schema. There is no explicit when-not-to-use guidance, but the intended context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral facts: it is deterministic, free with no payment or account required, it never guesses (unstateable steps are marked documented:false or not_documented), and it does not pay or sign on the caller's behalf.

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, but it is one dense block that repeats the payer object/example already present in the schema and packs cost formatting, verifier paths, and caveats into a single run-on sentence. Nothing is wasted exactly, but the structure is 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, the description usefully details what comes back: per payment type an ordered list of machine-readable steps, the cost fields, USD conversion only for recognised USD stablecoins, and the documented:false convention. Minor gaps remain around tracing/labeling behavior details, but coverage is good for a 5-param, 0-required read-only tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning: it clarifies target='verifier' selects the Verifier's own live price/free paths, that payer must be an object (not a string) and omitting it shows every option, and that agent_id is an unauthenticated stats-only label and trace_id continues a prior Concierge conversation.

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 — explains step-by-step how a listing is paid for and what it costs — and enumerates the exact output shape (ordered steps, cost in amount/asset/network/USD, cheapest usable option). It is clearly distinguishable from siblings like describe_listing and get_listing, which describe content rather than payment paths.

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?

States the two input modes ('Give listing_id, or target verifier') and sets a scope exclusion ('This tool only explains; it never pays or signs for you'), plus that it is free and requires no account. It does not explicitly name a sibling alternative to use for other needs, so it falls short of a full when/when-not/alternatives statement.

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 mark it read-only, idempotent, non-destructive, and closed-world. The description adds substantial behavioral context: it is not paginated, returns a small fixed number of buckets per dimension, includes zero-count categories, counts no_connection_declared and no_payment_declared, and requires no payment or account.

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 purpose is front-loaded, but the description is bloated with full enumerations of categories, connection types, and payment types that already appear in the schema. The opening sentence is also very long and introduces 'import source' without later detailing it. It is usable but does not tightly earn every sentence.

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 12-parameter, non-paginated aggregation tool with no output schema, the description does well: it explains bucket behavior, zero counts, and shared filters with search_listings. It stops short of fully describing every returned dimension, such as import source or payment-network buckets, leaving minor gaps.

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 most parameter meaning is already in the schema. The description still adds value by clarifying that q and max_price are the same as in search_listings and specifying that max_price is a USD amount matched only against recognized USD stablecoins. It does not add detail for every parameter, but it meaningfully extends the schema on price filtering.

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 operation: facet counts of matching listings grouped by dimensions. It distinguishes itself from search_listings by explaining it is for seeing what's out there before narrowing a search, rather than paging through listings. The verb+resource framing is clear.

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 explicitly says to use this before deciding how to narrow a search and as an alternative to paging through everything with search_listings. It names search_listings as the related tool and explains the shared filter semantics. The when-to-use guidance is direct and actionable.

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), yet the description layers on substantial behavior: it evaluates nothing, never sends the request, is deterministic, is free with no payment or account, and reads parameters from the verifier's live documents. That is rich context 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-loads the core purpose in the opening clause and keeps the key negative constraint ('It evaluates nothing itself') prominent. However, the dense run-on enumerations of field names and path details make individual sentences heavy, with some redundancy between the leading phrase and the later negative 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?

With no output schema, the description carries the burden of describing the return content (request body, free path with MCP URL/tool/allowance/limit-fit, paid path with endpoint/price/networks/protocol) and does so thoroughly, along with its non-evaluating, non-sending nature. An agent has everything needed to call it and interpret the result.

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 is already documented in the schema; the description's clarification of listing_id vs. output_schema (and their template vs. inline semantics) largely restates the schema. The enumerated field names (task_id, expected_schema, submitted_output, rules, bounds, enforce_rules) describe the produced body rather than input parameters, so they add little to input semantics.

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 ('Prepares the exact call to the Agent Output Verifier for one output') and enumerates exactly what it produces (request body, free path, paid path). It also distinguishes its scope by declaring what it does not do (no schema check, no rule check, no verdict, never sends the request), so an agent knows it is a builder, not an evaluator or sender.

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 clear conditional usage for the two mutually exclusive inputs ('Give listing_id ... or an inline output_schema') and notes it is free and needs no account or payment. It does not explicitly name or exclude sibling tools (e.g., describe_listing, build_template), so routing vs. alternatives is left to inference.

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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds substantial behavior beyond that: the dry-run default, per-client rate limit, ranking of new listings behind probed ones, a one-time health probe at creation, and that it is free with no account. 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?

Front-loaded with the core purpose, then progressively deeper detail on validation results, submit semantics, and ranking. It is dense and parenthetical-heavy but nearly every clause carries operational information; a small amount of redundancy remains around the submit path.

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, zero-required, no-output-schema mutation tool, the description names the return fields (errors, normalized_listing, missing_value, duplicate, claim_instead), the creation semantics, the ranking consequence, and the signing follow-up. An agent has enough to call it correctly in either mode.

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 goes further by grouping the fields that matter for discoverability ('name, description, endpoint_url, your submitted_by wallet address, connections, payment methods') and by tying outputs to inputs (missing_value lists what would make you findable), which helps an agent prioritize which of the 22 optional parameters to supply.

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 states a specific verb and resource ('get your service listed on the Agent Discovery Board') plus the second mode ('claim a listing that is already here'). That dual framing is enough to separate it from siblings like build_template, describe_listing, and get_listing without opening any 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 explicitly distinguishes the default validate-only behavior from 'With submit: true it creates the listing', and explains the duplicate/claim_instead path when the service already exists. It stops short of naming a concrete alternative sibling tool (e.g. build_template or describe_listing) for pre-registration exploration, so it is clear context rather than full routing.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior beyond them: the board is unvetted/self-reported, `badge` is the only evidence-backed signal with null meaning 'no data', stale/stale_reason semantics with the 60-day default, test listings hidden by default, error shape (isError with stable error_code and next_actions). That is exactly the kind of 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?

The critical caveat (self-reported, unvetted) is correctly front-loaded, but the description is an extremely long single block that re-enumerates filter values and behaviors already fully documented in the schema. Several sentences earn their place; the total is heavier than needed for an agent to select and call the 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 16 parameters, no output schema, and no required fields, the description compensates thoroughly: it describes response fields (stale, claimed, source, badge, next_actions, next_cursor), pagination rules, error behavior, and the trust caveats. Nothing an agent needs to call this 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-parameter semantics the schema states only per-field: filters 'all combine with q', and max_price + payment_network must be satisfied by the same payment_option. It also explains the practical effect of `q` on ordering. Still largely duplicative of the schema text, so not a 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?

Opens with a specific verb+resource ('Searches and browses the Agent Discovery Board') and immediately scopes what the directory contains (self-submitted offerings/requests/announcements/notices plus imported third-party profiles). It names siblings (get_listing, list_facets, get_template) so an agent can distinguish browsing/searching from single-item retrieval or facet counting.

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 explicit when-to-use guidance: no `q` means recency ordering, `q` means relevance-first full-text with fuzzy fallback; compact=true for scanning many results; cursor vs legacy offset ('prefer cursor'); don't reuse a cursor across different `q`. It also routes to the correct alternatives ('See also get_listing, list_facets, get_template').

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