docs-mcp

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

Discloses behavior the annotations cannot: results are relevance-ordered, content is markdown with urls, 'platform' filters post-retrieval and can cut a 15-section response to 1-2, while 'version' is applied during retrieval and only deduplicates per-version pages. The version-neutral inclusion rule (Cloud, Connect, Agentic Data Plane, API reference) is a non-obvious side effect that is fully spelled out.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return format, then organized around the two filter parameters, with each sentence carrying real decision value. It is long, however, and the version/platform mechanics are restated almost verbatim in the schema descriptions, so there is some redundancy to trim.

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 7-parameter search tool with no output schema, the description covers return format, ordering, filtering behavior, defaults for omitted parameters, and the effect of each filter on result size. Nothing an agent needs in order to call it well 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 meaning well beyond it: the retrieval-stage versus post-retrieval distinction between 'version' and 'platform', the 'current' shortcut, and the concrete size impact of each filter. This is exactly the semantic layer the schema alone cannot 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?

States a specific verb and resource ('Search the official Redpanda documentation') plus the return shape (sections with url and markdown content). The scope ('all queries that require Redpanda knowledge') clearly separates it from siblings like search_api_reference or get_config_property, which cover narrower corpora.

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 routing guidance ('use this tool for all queries that require Redpanda knowledge') and detailed when/when-not advice for the platform parameter, including the tradeoff of more context versus fewer results. It stops short of naming sibling tools or stating exclusions (e.g., that API reference or config lookups should go elsewhere), so 4 rather than 5.

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=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-schema behavior: a hard batch limit of 10 pages and a domain restriction (URLs must be from docs.redpanda.com/api/doc/*). It stops short of describing truncation or failure behavior for invalid URLs.

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 return contents, then usage, then constraints. Three short paragraphs with no filler; only mild redundancy between the 'up to 10 pages' sentence and the schema's maxItems note.

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?

Because there is no output schema, the description carries return-value explanation and does so ('parameters, request/response schemas, and examples'). Combined with annotations, usage routing, and constraints, an agent has enough to call it correctly; only error/invalid-URL handling is 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 coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by declaring the accepted URL origin (docs.redpanda.com/api/doc/*), which the schema does not state, and by reinforcing the max-10 batching for the urls array.

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 ('Retrieve full content of API reference pages') and enumerates what the response contains (parameters, request/response schemas, examples). This is clearly differentiated from the list/search siblings, which return page references rather than content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this after finding pages via list_api_reference_pages or search_api_reference' and instructs the agent to pass URLs from those results directly. The when-to-use condition and the alternative tools are both named, leaving nothing 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 read-only, non-destructive, closed-world, so the safety bar is covered. The description adds genuine value beyond that: deterministic reads of a generated dataset, no LLM/search involved, and the failure mode (found=false with close-name suggestions rather than a guess). It does not mention pagination or output shape, but the output schema exists to cover that.

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 verb+resource+return payload, then determinism, then routing advice. Dense but every clause carries information; the 'no LLM or search is involved' phrasing is slightly redundant with 'deterministic' but earns its place as a disambiguation signal.

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 single-lookup read tool with an output schema and full parameter documentation, nothing an agent needs is missing: what it does, what it returns, what happens on a miss, version/platform scoping, and which sibling to prefer are all 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 coverage is 100%, so all five parameters are already documented in structured form. The description reinforces only two things the schema already states – that 'name' must be exact and that platform='cloud' answers Cloud availability – and adds no new syntax or format detail. 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 (look up), resource (one Redpanda configuration property), and scope (cluster, broker, or topic) plus exactly what is returned. It is clearly distinguishable from list_config_properties (enumerates) and ask_redpanda_question (free-form Q&A).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use this *before* ask_redpanda_question for questions about a specific property's default, type, or availability, and names the platform='cloud' case. The 'exact name' requirement and the alternative behavior for unknown names are both spelled out.

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/non-destructive/closed-world, yet the description adds deterministic behavior, provenance (generated schema for the published release), and crucially the not-found contract: found=false plus a cross-type hint (redpanda input vs redpanda output). That is exactly the failure-mode context an agent cannot get from 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 action and the row-shaped return, then the field drill-down, then the not-found behavior, then the routing rule. Dense but almost every clause carries information; the long enumeration of return columns borders on over-packing for a single paragraph.

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?

Even with an output schema present, the description covers the things the schema can't express: determinism, source of truth, the found=false path with its cross-type message, and how to escalate to full field detail. An agent has everything needed to call this correctly and interpret a miss.

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; the description goes beyond by explaining what the optional 'field' parameter actually yields (description, examples, options, child fields) and by showing that field paths like 'cases[].check' are addressable. 'context'/'session_goal' are left to the schema, which is acceptable.

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?

Specific verb+resource ('look up one Redpanda Connect component') with the full enumeration of component types and the exact key (type + name). It is clearly distinct from the sibling list_connect_components, which only enumerates.

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 this before ask_redpanda_question for any question about a specific component or field.' The condition is precise, but it never states the converse (use list_connect_components when you don't yet know the name) or when ask_redpanda_question is still appropriate.

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=true, openWorldHint=false, destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: deterministic lookup from the published command tree, no LLM or search, found=false with suggestions for nonexistent commands, deprecated commands returning deprecation notes and replacements even when hidden, and unknown versions returning the published version list.

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 verb and the return payload; the routing rule lands last, which is defensible. Some mild over-elaboration (the parenthetical about the command tree and the redundant 'no LLM or search is involved'), but nearly every clause carries real information for the caller.

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?

An output schema exists so return values need not be described, yet the description still sketches them. For a read-only lookup tool with full annotation coverage, full schema coverage, and an output schema, nothing an agent needs to call it correctly or interpret a negative result 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. The description still adds meaning beyond the schema: the name may omit the leading 'rpk', may use aliases at any level, or may be the page name ('rpk-topic-create') — forms the schema's single example ('rpk topic create') does not convey. It does not elaborate on context/session_goal, but those are self-documenting.

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?

Specific verb and resource ('look up one rpk CLI command by its full name') with an explicit enumeration of what comes back: usage, help text, flags with types and defaults, aliases, subcommands, scoping, plugin/release, docs URL. It is clearly distinguished from the sibling list_rpk_commands (singular lookup vs listing) and from ask_redpanda_question.

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?

Explicit routing rule: 'Use this before ask_redpanda_question for any question about a specific rpk command's flags, defaults, or existence in a release.' It also states acceptable input forms and the failure mode (found=false with close-name suggestions), 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.

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

Goes beyond the annotations by disclosing what happens on the write (the report is recorded), what comes back (a short confirmation, not documentation), and a privacy constraint (no name/email, never credentials or tokens). The annotations already flag readOnlyHint=false and openWorldHint=true, and this text usefully adds the outcome and data-handling rules that annotations cannot express.

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?

Four sentences, front-loaded with the action and the eligible problem types, then workflow guidance, then return shape, then the privacy constraint. Nothing is repeated from the schema and 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?

For an 8-parameter write tool with no output schema, the description covers the missing pieces: it states the return value is a short confirmation rather than docs, warns that nothing identifying is stored, and constrains the input. Combined with 100% schema coverage, an agent has everything needed 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 description coverage is 100%, so every parameter including the enum categories and severity defaults is already documented in structured data; baseline 3 applies. The description adds only light guidance (detail sufficient to fix, include the page URL) and does not explain how fields like context, expected, or session_goal should differ from message, so it does not meaningfully exceed 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 (report a concrete problem to the Redpanda docs team) and then enumerates the qualifying problem classes: missing/unclear/outdated/wrong docs, misbehaving docs tools, and product issues. This cleanly separates it from the read-oriented siblings (search_api_reference, get_config_property, ask_redpanda_question), which none of them do.

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 timing ("call it when you notice the problem"), an explicit exclusion ("Do not call it to test the tool"), and quality guidance ("with enough detail to fix it, including the page URL when you know it"). An agent knows both when to fire it and the one case where it should not.

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=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered; the description adds meaningful value by describing the return payload shape (endpoints, schemas, topic pages with URL/title/type/description), which matters since no output schema exists. It omits pagination or result-size behavior, keeping it short of a 5.

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 purpose sentence, then a labeled SCOPING block, then a routing sentence at the end — a clean structure with no filler. The per-API bullet list is somewhat long and partially restates the schema's api description, costing a point on tightness.

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 read-only browse tool with no output schema, the description covers purpose, scoping, return shape, and the sibling alternative — enough to call it correctly. The remaining gap is the url parameter's behavior and any pagination/result-limit expectations.

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; the description earns a step up by expanding each api value into what it actually covers (e.g. admin = brokers, partitions, configs, users), which is semantic enrichment beyond the schema's short enum-like listing. The url parameter, which controls the listing root, gets no treatment in the description.

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 ("List pages in Redpanda API reference documentation") and immediately enumerates what comes back (endpoints, schemas, topic pages with URL, title, type, description). It also names the sibling it is not (ask_redpanda_question), so an agent can separate browsing from question-answering without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use this to browse API structure" plus the explicit alternative for general docs gives clear usage context and one exclusion. However, it does not distinguish this from the most directly competing siblings, search_api_reference and get_api_reference_content, which an agent would plausibly confuse with a listing call.

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/non-destructive, but the description adds real behavioral context beyond them: name matches rank above description matches, deprecated properties are hidden by default, and total=0 explicitly means no match with no fallback guess. It does not mention limit or pagination behavior, but the schema covers that.

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?

Roughly five sentences, each carrying distinct information (purpose, return shape, ranking rule, deprecation default, routing to sibling, empty-result semantics) with purpose front-loaded. Nothing repeats structured fields verbatim.

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 9-parameter read-only search tool with an output schema and full schema coverage, the description covers purpose, result shape, ranking, default filtering, and the meaning of an empty result. An agent has everything needed to call it and interpret the outcome 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; the description still adds meaning by explaining that the keyword matches both names and descriptions, that scope/platform/enterprise act as filters, and that include_deprecated changes result visibility. It does not add syntax detail for version beyond what the schema already says.

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 ('Search Redpanda configuration properties') plus the matching axes (keyword in name or description, filters by scope/platform/enterprise). It is clearly distinguishable from the sibling get_config_property, which fetches a single property by name.

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 to find the right property name before get_config_property, or to answer which properties control X.' Names the alternative and the condition that selects it, and no hidden exclusions are 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?

While the annotations provide a strong safety profile (readOnly, non-destructive), the description adds critical behavioral context beyond structured fields: it discloses the return format ('compact rows with docs URLs'), search ranking logic ('Name matches rank above category and summary matches'), and how to interpret an empty result ('total=0 means nothing 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?

The description is highly efficient and front-loaded. Every sentence provides necessary information—purpose, search behavior, return format, usage guidance, and edge-case handling—without any fluff.

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

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

Given the complexity of the tool (7 optional parameters) and the existence of an output schema, the description is complete. It equips the agent with everything needed to call the tool correctly and interpret both its results and its empty state.

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%, establishing a baseline of 3, but the description adds valuable semantic context. It clarifies exactly what the keyword query searches against ('matched against name, categories, and summary') and explains the ranking behavior, which is not captured in 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 ('List or search') and resource ('Redpanda Connect components'), along with the filtering dimensions. It distinguishes itself from the detail-oriented sibling tool by explicitly positioning itself as a discovery mechanism for use 'before get_connect_component.'

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?

Provides explicit when-to-use guidance ('Use it to discover what exists... before get_connect_component') and gives concrete examples of use cases ('every Services input, or every output available in Cloud'). The alternative tool is explicitly named.

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/no-open-world annotations it discloses ranking behavior (name matches rank above help-text matches), the deprecation default, and that total=0 is authoritative with no fallback. It doesn't cover pagination mechanics beyond the limit cap or anything about response ordering ties, so it stops short of fully exhaustive.

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, then filter modes, then return shape, then selection guidance — a sensible ordering with no filler. It is dense (four sentences of packed clauses) but nearly every clause carries operational information; only the returned-fields enumeration edges toward redundancy with the output 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?

For an 8-parameter, zero-required list tool with an output schema, the description supplies what the structured fields cannot: ranking, deprecation behavior, and the semantics of an empty result. Nothing an agent needs to invoke 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; the description earns above that by clarifying that the keyword is matched against both command names AND help text (the schema only says 'Keyword'), and by giving a concrete parent example ('rpk topic' lists direct subcommands). It does not explain how multiple filters combine (query + parent + plugin), which is the main remaining ambiguity.

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 (list/search rpk CLI commands for a docs version) and explicitly positions itself against the sibling get_rpk_command as the discovery step that precedes it. An agent can distinguish it from get_rpk_command and the API-reference list tools 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?

Names the trigger scenarios directly ('find the right command name before get_rpk_command', 'which rpk commands do X') and defines the zero-result contract so the agent knows not to retry or guess. Filter modes (query/parent/plugin) are each given a purpose, which amounts to explicit 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered; the description adds behavior beyond that with the "up to 20 results" cap and the per-result fields returned. It does not discuss relevance ranking, pagination, or what happens when zero results match, but for a read-only search that is a minor omission.

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 return shape are front-loaded in the first sentence, and the bullets are scannable. There is some redundancy between the SCOPING list and the WHEN TO USE WHICH examples, which repeat the same mappings in a second form, costing a little length for an otherwise tight definition.

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 1 required parameter, 100% schema coverage, and no output schema, the description supplies the one thing the schema cannot: how to pick the `api` scope and what the results contain. Nothing an agent needs in order 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 baseline is 3, but the description adds real semantic content by explaining what each `api` scope actually contains (admin = brokers/partitions/configs/users, cloud-dataplane = topics/ACLs/connectors), which the schema enum list alone does not convey. It gives no guidance on `type`, `context`, or `session_goal`, but those are already documented in 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 ("Search Redpanda API reference documentation by keyword") and immediately describes the return shape (up to 20 endpoints, schemas, or topics with URL, title, text excerpts). It also explicitly routes non-API questions to the sibling ask_redpanda_question, so an agent can distinguish it without opening another 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?

The SCOPING and WHEN TO USE WHICH blocks give explicit scope-to-value mappings plus concrete query examples ("broker endpoints" -> admin, "create topic API" -> all) and an exclusion routing general questions to ask_redpanda_question. This is the strongest part of the definition — when-to-use, when-not, and the alternative are all named.

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