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

Annotations already cover read-only and idempotent semantics, yet the description adds real value: it promises credentials are never exposed ('never the token') and flags that an optional network probe to QQ can be performed, which is behavior not visible in the schema.

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

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

Two compact sentences, no filler: the status fields are front-loaded and the optional probe follows as a secondary clause.

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 status tool with no output schema, the enumeration of reported fields is sufficient for an agent to know what it gets back. Only the probe parameter's exact semantics remain underspecified.

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 0% for the single probe_network parameter, so the description must compensate. It conveys that the optional switch triggers a live QQ gateway probe via get_gateway_bot, but never names the parameter, states the default-false behavior, or describes cost/latency of the network call.

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 ('Show local runtime status') and enumerates exactly what is reported: mode, credential presence, catalog version, event buffer, gateway/webhook state. It is distinguishable from siblings like query_api, though it does not explicitly contrast with the similarly named event_stream_status.

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 closing clause hints at an optional diagnostic action ('Optionally probe QQ with get_gateway_bot'), which implies when to enable the probe, but there is no explicit when-to-use/when-not guidance or comparison to sibling status tools.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: the buffer is dropped in bulk and the transport keeps running, clarifying the blast radius of the destructive action.

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

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

Two compact sentences with no waste; the action and its main constraint are front-loaded before the usage hint.

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 zero-param, no-output-schema tool whose annotations already flag it as destructive and idempotent, the description is nearly sufficient. A brief note on whether in-flight or already-delivered events are untouched would close the remaining 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?

Zero-parameter tool, so the baseline is 4. The description adds no parameter claims, which is correct since there are none to describe.

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 ('Drop all buffered events') plus a key scope qualifier ('without stopping the transport'), which separates it from poll_events/wait_events that consume events. It doesn't explicitly name a sibling 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?

'Useful after testing' gives a weak situational cue for when to call it. There is no explicit when-not guidance (e.g., don't use in production flow, doesn't affect already-delivered events), leaving alternatives 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?

The description says it downloads into QQBOT_MCP_DOWNLOAD_DIR and returns a local path, which means it creates a local file. That contradicts the readOnlyHint=true annotation, which claims the tool does not modify its environment. The SSRF guard and size cap disclosures are useful, but the annotation contradiction is decisive.

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

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

Two dense sentences with no filler. The core action, destination, safeguards, and return value are all front-loaded.

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

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

No output schema exists, and the description usefully states that a local path is returned. However, with 0% schema description coverage, it omits filename handling, max_bytes details, overwrite behavior, and failure modes, so it is only minimally complete for a 3-parameter 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 description coverage is 0%, so the description must compensate and only partially does. It clarifies that the URL is an attachment URL and implies max_bytes via 'size cap', but never mentions the filename parameter or explains defaults, limits, or behavior when the size cap is exceeded.

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: download an attachment URL, with examples of message images/files and media URLs. The destination directory and returned local path make the scope clear, and no siblings overlap with this attachment-downloading behavior.

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

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

The description makes clear that this is for downloading message image/file/media URLs, which is enough context to select it over the API/event siblings. It does not explicitly state when not to use it or name alternatives, but no alternative download tool exists among the siblings.

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 and idempotentHint, so the safety profile is covered. The description adds useful scope by enumerating what is inspected (transport config, gateway, webhook, buffer), but says nothing about freshness of the status, cost, or whether it performs live probes that could be slow.

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

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

A single front-loaded sentence with no filler. Every element named (transport configuration, gateway, webhook, buffer) conveys distinct information about the payload.

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 parameters, no output schema, and read-only annotations, the description is nearly sufficient; it lists the returned sections so the agent knows what to expect. A brief note on when this diagnostic is warranted would close the remaining 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?

The tool takes zero parameters, so there are no parameter semantics to explain; the schema is empty and fully documented by its absence. Baseline 4 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 ('Show') and a concrete resource set: event transport configuration plus gateway, webhook and buffer status. An agent can tell this is a diagnostic/inspection tool, though it does not explicitly distinguish itself from the adjacent sibling bot_status.

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?

There is no when-to-use or when-not-to-use guidance. An agent must infer from the name alone whether to call this versus bot_status or poll_events when troubleshooting event delivery, and nothing in the description says which condition selects this tool.

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 and idempotent, so the safety profile is covered and the description is free to spend its words on content coverage and sequencing relative to invoke_api. It adds real context — what the agent will find in the returned docs and why to fetch them first — without describing freshness or caching, which keeps it below 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?

Two sentences with no filler: the first enumerates the payload, the second gives the actionable instruction. Content is front-loaded and the ordering advice lands last where it is easiest to act on.

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, yet the description compensates by listing exactly what the response contains (schemas, response fields, error codes, rate limits, examples). Combined with the invocation hint, an agent has everything needed to decide to call it and to 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 coverage is 100% and the schema already explains the single 'name' parameter with a concrete example alias, so the description adds nothing parameter-specific beyond 'one API'. Baseline 3 is the correct ceiling here.

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 ('Get the full documentation for one API') and immediately enumerates what that documentation contains (path/query/body schemas, response fields, error codes, rate limits, examples). This reads clearly as a single-resource doc fetch, distinct from discovery siblings like list_apis and search_apis.

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 an explicit workflow trigger: 'Call this before invoke_api for non-trivial bodies,' which tells the agent when to reach for this tool. It does not spell out the inverse case (skipping it for trivial calls is only implied by 'non-trivial'), so the exclusion is inferred rather than stated.

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

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

Annotations already establish this as a read-only, idempotent operation, so the description needn't repeat safety details. It adds useful behavioral context by saying the result includes the payload schema, required intents, and examples, which tells the agent what information it can rely on. It does not cover behavior for unknown event names or error handling.

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

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

A single sentence that front-loads the action and result, with concrete examples appended. No filler or redundant restatement of the tool name.

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 simple one-parameter read tool with annotations and no output schema, the description covers the essential outputs (payload schema, required intents, examples). The only material gap is the lack of explicit guidance on the 'name' parameter and unknown-name behavior.

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?

The schema has only one parameter ('name') with 0% description coverage, so the description needs to compensate. The examples strongly imply that 'name' should be an event type identifier, but the description never states this explicitly or gives format constraints beyond the sample values.

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 ('Get one event payload schema') and concretely lists what comes back: required intents and examples. It implicitly contrasts with the sibling 'list_event_types' by emphasizing a single event type, but does not name that alternative explicitly.

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 examples ('C2C_MESSAGE_CREATE', 'GROUP_AT_MESSAGE_CREATE') and by the fact that it fetches one event type's schema. However, there is no explicit statement of when to use this versus 'list_event_types' or when it is inappropriate.

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 and idempotentHint=true, so the safety profile is covered without the description. The description adds the catalog's scope (103 endpoints, 21 categories) and its entry-point role, but says nothing about return shape, pagination, or result ordering for a 103-item catalog. That is a real gap for a listing tool, though the annotation coverage lowers the bar.

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

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

Two sentences with no filler, and the most decision-relevant information (what it lists, catalog size, discovery role) is front-loaded. Every sentence carries weight.

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 no-required-parameter, read-only listing tool with fully documented parameters and annotations covering safety and idempotency, the description supplies enough to call it correctly. The only shortfall is not clarifying how results are returned or how it relates to search_apis when results are large.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, establishing a baseline of 3. The description restates the three main filter axes (category, keyword, read/write) without adding syntax or semantics, and it omits include_legacy entirely, so it does not exceed what the schema provides.

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 ('List QQ bot APIs from the local catalog') and sizes the catalog (103 endpoints, 21 categories), which tells an agent exactly what it is enumerating. It clarifies the discovery role ('first call to discover what the bot can do'), though it stops short of naming the near-sibling search_apis, so an agent must still infer the boundary between the two.

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?

'This is the first call to discover what the bot can do' gives clear context for when to reach for it, and the filter axes hint at refinement. However, there is no explicit exclusion or routing rule versus search_apis, query_api, get_api, or list_categories, so the alternative-selection guidance is only implied.

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

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

The annotations already declare this operation to be a safe, idempotent read. The description adds useful information about the return payload ('with endpoint counts'), which goes beyond the annotations. It doesn't say whether the listing is paginated, whether the categories are scoped to the workspace, or what else it returns.

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 a single front-loaded sentence with no wasted words, and the resource and the payload detail are stated immediately.

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 zero-parameter, read-only enumeration tool with no output schema, the definition covers the essentials: what is listed and that counts are included. A short note on how categories relate to list_apis or get_api would make it fully complete, but this is not a serious 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?

The schema has zero parameters, so the baseline is 4. Because there are no inputs to explain, the description does not need to describe parameter meaning, and the description correctly says nothing about parameters.

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 contains a clear verb ('List') and a clear resource ('catalog categories'), and it notes that the count of endpoints per category is included. This distinguishes it from list_apis and list_event_types, but it doesn't explicitly state how a 'category' relates to those sibling resources.

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 use case is implied: enumerate categories, probably as a first step before calling list_apis or get_api. However, the description states no explicit condition for when to call it, and it names no alternative, even though list_apis and list_event_types exist and could confuse an agent.

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 and idempotentHint, so safety is covered; the description adds the total event count and the availability of intent/category filtering. It says nothing about return shape (flat list vs grouped), ordering, or whether all 53 come back at once, so it adds only modest 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?

Two short sentences with the resource and count front-loaded, followed by the sibling routing pointer. No filler and nothing that could be trimmed without losing meaning.

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 simple three-parameter read-only list tool this is close to adequate, but with no output schema the description should at least hint at the result structure, and with 67% of parameters undocumented it should define 'category' and 'keyword'. As written an agent may call it successfully but cannot predict the response or the accepted filter vocabulary.

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 only 33%: 'intent' is well documented with enumerated names and bit values, but 'keyword' and 'category' have no descriptions at all. The description compensates partially by confirming intent and category act as filters, but it never mentions 'keyword' or explains acceptable category values, leaving a real gap.

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 QQ gateway/webhook event types'), gives the cardinality (53), and explicitly separates itself from the sibling get_event_type, which returns payload fields. An agent can distinguish this from get_event_type and list_categories 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?

Explicitly routes detail lookups to get_event_type and indicates filtering is optional, so the when-to-use-this-vs-sibling choice is clear. It does not state when not to use it (e.g., when you already know the event name), so it falls short of full exclusion 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?

Discloses the non-obvious destructive default ('Consumes returned events by default') and the exact escape hatch (peek=true to keep them), which the boolean parameter's schema entry does not convey at all. It also names the runtime prerequisite (event transport running). Note the tension with readOnlyHint=true, since draining a buffer is a state change; the description is the more accurate of the two signals.

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

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

Three short sentences: purpose first, then the side-effect/escape-hatch pair, then the prerequisite. No filler and nothing buried.

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 four optional parameters and no output schema, the description covers the two facts an agent could get wrong (consumption semantics and the transport prerequisite). It stops short of describing return shape or ordering relative to since_seq, which the agent must infer from the schema.

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

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

Schema coverage is only 50% (peek and limit have no schema descriptions), and the description fully compensates for the important one by explaining that peek=true preserves events instead of consuming them. limit, types and since_seq are either self-explanatory from the schema or left undocumented, but their meaning is recoverable.

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: 'Read buffered gateway/webhook events'. An agent immediately knows the operation, though the description never distinguishes it from the sibling wait_events or event_stream_status, which are the closest alternatives.

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?

'Requires event transport to be running' is a useful precondition and the peek flag is framed as a conditional choice. However, there is no guidance on when to poll versus wait_events or check event_stream_status, so the agent must infer the selection rule from sibling names alone.

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 and openWorldHint, so safety is covered structurally. The description adds the access-tier requirement and the note that bodies are rare for read APIs, but says nothing about rate limits, error behavior, or what a response looks like. That is a modest value-add above annotations, consistent with a 3.

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

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

Three short sentences, front-loaded with scope and examples, then permission, then the write alternative. No redundant or filler content.

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 generic dispatcher with no output schema and fully documented parameters, the description covers scope, examples, access tier, and the write alternative. It stops short of error semantics and response expectations, but nothing essential to invoking 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 description coverage is 100%, so all four parameters (api, body, path, query) are already documented in the schema, including the path-parameter example. The description adds only the hint that body is rare for read APIs; it does not clarify api-name/alias resolution or nested object formats 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 specific verb ('Call') and resource ('read-only QQ API, GET endpoints'), with concrete endpoint examples that make the operation tangible. It distinguishes read from write by routing to invoke_api, though it does not differentiate execution from discovery siblings like list_apis or get_api.

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 gives a prerequisite ('Read mode or higher') and names the alternative for the opposite case ('For writes use invoke_api'). It does not say when to use this versus list_apis/get_api/search_apis for API discovery, leaving one routing gap.

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 and idempotentHint, so the safety profile is covered. The description still adds real value beyond them: it discloses result ordering ("ranked matches"), the returned fields (method, path, read-only flag), and bilingual query support — all information not present in the annotations or in any output schema.

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

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

A single sentence that front-loads the verb and resource and packs in the return shape and keyword scope without a wasted clause.

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 two-parameter read-only search with no output schema, the description supplies the essentials: what is searched, how it is matched, and what the results contain. The only gap is result-set sizing (the `limit` parameter and default behavior), which an agent would have to read from the schema.

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

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

Schema coverage is only 50%: `query` is documented with concrete examples in the schema and reinforced by the description's "Chinese/English keywords" note, but `limit` (default 20, max 50) is undocumented in both schema and description. The description adds marginal meaning for the required parameter but does nothing to compensate for the undocumented one.

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 APIs") plus the query mode (Chinese/English keywords) and what comes back (method, path, read-only flag). It implicitly distinguishes itself from list_apis by being keyword-driven, but never names or contrasts with the sibling tools that overlap most (query_api, list_apis).

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 keyword-search framing implies when to use it rather than browsing everything, but there is no explicit when-to-use/when-not guidance and no mention of when query_api or list_apis would be better. Usage must be inferred from the sibling names alone.

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 real behavior beyond the annotations: default 30s and 5min max wait, immediate return of buffered matches, otherwise blocking until a gateway/webhook event arrives, and cancellation on client abort. These are non-obvious latency and lifecycle semantics that an agent must plan around. It stops short of 5 because the return shape/cursor behavior is never described.

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 the long-poll framing, then timing, then return behavior, then cancellation. Every sentence carries information and there is no filler.

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

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

No output schema exists, so the description should say more about what a returned event looks like and how since_seq interacts with returned sequence numbers. The blocking/timeout/cancellation story is complete, but cursor and peek semantics — the parts most likely to cause misuse in a long-poll loop — are absent.

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 0% across 5 parameters, so the description carries the full burden — yet it only explains timeout_ms (default 30s, max 5min). The semantically loaded parameters, especially since_seq (cursor) and peek (presumably non-consuming read), are left entirely undocumented in both schema and 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 ('Long-poll for new events') with the key distinguishing trait — blocking long-poll rather than a snapshot poll — which implicitly separates it from the sibling poll_events. It does not explicitly name or contrast that sibling, 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?

The blocking nature and timeouts imply when this tool fits (waiting for a gateway/webhook event rather than fetching a snapshot), but there is no explicit 'use this instead of poll_events when...' routing and no stated preconditions. Usage is inferred rather than directed.

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