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

Annotations already declare readOnlyHint and openWorldHint, but the description adds substantial behavioral context: it prefers author-accepted answers when the Q&A plugin is installed, falls back to the strongest reply otherwise, and always labels which approach it used so unconfirmed replies are not presented as confirmed answers. This is exactly the kind of source-quality and fallback disclosure an agent needs beyond safety hints.

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

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

Three sentences with zero waste, front-loading the core action and then adding the important fallback and routing context. Every sentence earns its place.

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?

The description covers purpose, preferred usage, fallback behavior, and plugin dependency well, and annotations cover safety. With no output schema, it could say more about the shape of the extracted answer or how results are structured, but it does signal that each answer is labelled by source, which is likely enough for correct invocation.

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 five parameters are already documented in the schema. The description does not add parameter-level meaning such as what depth controls or how category/tag filters combine, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Find topics that already answer a question, and extract the answer from each') and distinguishes itself from siblings by positioning as the first tool to reach for when a question may have been seen before. It also clarifies Q&A-plugin-dependent behavior, which helps differentiate it from generic search tools.

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 reach for this first when someone asks a question the forum may have seen before, giving clear context for use. It does not name alternatives to avoid or state when-not-to-use conditions, so it stops short of a full routing guide.

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 openWorldHint=true, so safety is covered. The description adds real behavioral context beyond them: the specific capabilities probed and the fact that the response explains what is missing and what would enable it. It does not mention cost or latency of probing, which keeps 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?

Two sentences, no filler. The capability list comes first and the routing guidance second, which is the correct front-loading for a diagnostic tool.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so at a useful level: per-feature usability plus an explanation of what is missing and what would enable it. Slightly more detail on the response shape (e.g. per-feature status fields) would make it fully self-contained.

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

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

Only one parameter (refresh) and schema description coverage is 100%, with the schema itself explaining the caching behavior and the post-plugin-install use case. The description adds nothing about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Report) and resource (forum features this server can use), then enumerates exactly what is probed: reachability, authentication, full-text search, the Q&A plugin, and the Shotef triage plugin. This clearly separates it from siblings like search_forum or get_triage_status, which consume features rather than diagnose them.

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 trigger conditions: call it first when a result looks thin, or when a tool reports a feature as unavailable. That is strong when-to-use guidance, though it does not state when not to bother (e.g. after a successful call) or name alternative diagnostics.

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 openWorldHint=true, so the safety profile is covered. The description usefully notes that the parent topic is returned alongside the post, but says nothing about behavior on an invalid or deleted pid, nor about the result shape. Adds modest value over the annotations, not rich behavioral context.

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

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

Two short sentences, front-loaded with the action and the return scope, then the usage condition. Every clause earns its place with no redundancy.

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 one-parameter read tool with no output schema, the description covers the input, the return scope (post plus topic), and the use case. It is close to complete; only error/edge-case behavior is left unstated, which is minor 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% and the single pid parameter is fully documented in the schema, including the /post/<pid> format and an exclusiveMinimum constraint. The description only restates 'by its id' and adds no syntax or constraint detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read one post by its id') and adds scope by noting the parent topic is included. It implicitly separates itself from get_topic and search_forum by emphasizing a single reply, though it never names those siblings outright.

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 a concrete trigger condition: 'when a search result or a link points at a specific reply and you only need that reply.' That distinguishes the single-post case from browsing, but it does not explicitly name get_topic as the alternative when the topic itself is wanted.

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. The description adds genuine behavioral context beyond that: the accepted-answer and triage-board fields are conditional on installed plugins, so the agent knows the response shape can vary. It does not mention pagination behavior, which the schema partly hints at.

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, zero filler, and the payload enumeration is front-loaded before the soft usage note. Every clause earns its place.

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 return contents, and it does so well (post, replies, accepted answer, triage position). Minor gaps: pagination interaction with page/max_posts and behavior on invalid tid are left unstated.

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 each of the three parameters (tid, page, max_posts) is documented with format/default context in the schema. The description adds nothing about parameters, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (read) and resource (topic) and enumerates what 'in full' means: original post, replies in order, accepted answer, triage position. It implicitly distinguishes itself from get_post (single post) and get_topic_answer (just the answer) by promising the whole thread, though it never names those siblings 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?

The closing sentence gives a use case ('understanding a reported issue in the reporter's own words'), which implies when to reach for it. But there is no explicit when-not guidance and no routing to the obvious alternatives (get_post, get_topic_answer, investigate_issue), so the agent must infer the boundary itself.

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 declare readOnlyHint and openWorldHint, so safety is covered. The description goes beyond that by disclosing two behavioral modes contingent on plugin presence (accepted answer vs. most-upvoted unconfirmed reply) and a no-guess policy for open questions – genuinely useful context an agent cannot get from annotations.

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

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

Two tight sentences, front-loaded with the core purpose and then the plugin-dependent behavioral nuance. No filler.

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

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

For a single-param read tool, the description covers purpose and the main behavioral contingency (plugin presence) that influences the returned content. No output schema exists, but the description does explain the nature of the returned answer, which compensates; a note on error handling for missing topics would complete it.

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?

Single required 'tid' integer with 100% schema coverage including 'Topic id.' and exclusiveMinimum. The description adds no syntax, format, or boundary detail beyond the schema, so the baseline of 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?

Clear verb+resource: retrieves the answer for a specific topic by id. It does not explicitly differentiate itself from siblings like get_post or find_answers, but the 'topic's answer' scope is specific enough to distinguish from a generic post fetch.

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?

Implied usage is 'fetch the answer for a known topic id', but the description gives no explicit when-to-use versus find_answers or get_topic, nor any preconditions. An agent can infer the context but is not guided to the alternative 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real value beyond that: it discloses the Shotef plugin dependency, the team-member token requirement, and the non-obvious fact that a non-member receives an explanation rather than an error. It stops short of describing pagination or result size limits.

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: what the board is, what it's for, and what it requires. The resource definition is front-loaded and every sentence earns its place.

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-required-parameter read tool with no output schema, the description covers content, purpose, prerequisites, and failure behavior. Nothing needed 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 description coverage is 100% and the single parameter's omission/default behavior is already documented in the schema ('Omit for the token holder's default team'). The description adds no syntax or semantics beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and enumerates exactly what the result contains ('every open ticket by workflow column, with priority, owner and age'). This level of detail separates it cleanly from siblings like get_triage_status and investigate_issue without needing to name them.

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 two concrete use cases: seeing current support workload and finding stalled issues. Clear context for invocation, but offers no explicit exclusions or alternative tools (e.g. when to prefer get_triage_status over this board).

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 readOnlyHint and openWorldHint, and the description adds genuinely new behavioral context: a hard dependency on the Shotef triage plugin and a graceful failure mode (reports cleanly and redirects to reading the topic). It does not address auth or caching, but for a read-only status lookup this is solid added value.

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 tightly written sentences, front-loaded with the returned states, then the question answered, then the plugin caveat. Every sentence earns its place; density is justified by the lack of an 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?

Without an output schema, the description must carry the return contract, and it does: enumerates the state values plus team and parked status. The plugin dependency and failure behavior close the remaining operational gap.

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

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

Schema coverage is 100% with a single documented tid parameter, so the schema carries the semantics. The description adds no identifier format or validity guidance, making 3 the appropriate baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (triage status of a topic) and enumerates the exact payload: workflow states (received, in progress, awaiting the reporter, closed), the handling team, and the parked flag. This lets an agent distinguish it from siblings like get_topic or get_triage_board 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?

Frames the use case crisply with the question it answers ('is anyone working on this, and was it ever resolved?') and names the fallback when the plugin is absent (read the topic instead). It stops short of contrasting itself with the board-level sibling get_triage_board or stating explicit when-not-to-use conditions.

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 openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the operation is expensive because it opens multiple topics, and it is positioned as a heavier sweep than find_answers. It does not describe pagination or return shape, but with annotations carrying the safety profile this is solidly above baseline.

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

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

The description is front-loaded with the full sweep's steps and closes with the disambiguation, and every sentence carries information. It is slightly long and lists behavior that partly overlaps the schema parameters, but 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?

For a 6-parameter, no-output-schema tool, the description covers intent, triggering context, cost, and the high-level shape of the result ('end with concrete next steps'). It does not describe the return structure at all, but the enumerated sweep steps give the agent a reasonable expectation of what comes back.

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 six parameters are already documented in the schema (depth, scan_pages, within_days, tags, categories, issue). The description only indirectly alludes to 'opens several topics' for depth and adds no syntax or format detail the schema lacks. Baseline 3 is correct when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and enumerates the actual operations of the sweep: find related topics, extract existing answers, separate open reports, fold in triage status, produce next steps. It explicitly contrasts with the sibling find_answers, so an agent can distinguish it without opening either schema.

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

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

It states the trigger condition precisely ('when someone reports a problem and you need to know whether the forum has seen it before...') and names the alternative with the selecting condition ('prefer find_answers for a plain question'), plus the cost tradeoff ('slower because it opens several topics'). This is explicit when-to-use and when-not-to-use 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 and openWorldHint=true, so the safety profile is covered. The description adds payload context (ids, descriptions, topic counts) that the agent cannot get from annotations or the empty schema, which is real added value. It stops short of noting the tree's hierarchy depth or whether counts are live, so not 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, zero waste. The return content is stated first and the routing guidance second, which is the right front-loading for a lookup tool.

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

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

With no output schema, the description carries the return-value burden itself and does so ('ids, descriptions and topic counts'). Combined with annotations covering the read-only/open-world profile and a paramless schema, 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?

Zero parameters, so the baseline of 4 applies. There are no arguments for the description to explain; the sentence correctly signals the tool is unconditioned by input.

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 (List) plus resource (forum's category tree) with scope detail: 'with ids, descriptions and topic counts'. That tells an agent exactly what comes back and distinguishes it from sibling reads like get_topic or search_forum.

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 states the purpose in workflow terms: 'Use it to find the category id to pass to search_forum, list_recent_topics, or investigate_issue.' That names three concrete downstream alternatives and the condition that selects them, 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 readOnlyHint and openWorldHint, so safety and network scope are covered. The description adds only the caveat that it works where search is unavailable; it says nothing about pagination behavior, result size, or rate limits. The auth requirement for the 'unread' source lives in the schema, not the description.

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 tight sentences, front-loaded with the action and mode list, then the rationale. No filler or redundancy.

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 listing tool with no output schema and fully documented parameters, the description covers purpose and usage adequately. It would be slightly stronger with a note on how paging interacts with the listings or a pointer to search_forum for filtered queries.

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 (cid, page, limit, source) is already documented, including the default and the auth note for 'unread'. The description restates the listing modes but adds no syntax, format, or interaction detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb (browse) and resource (topic listings) and enumerates the four listing modes that match the source enum, so the agent knows exactly what it returns. It also implicitly separates itself from search tools by framing itself as the exploration path, though it never names search_forum directly.

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 a clear use context ('getting a feel for what is being reported lately') and a fallback condition ('the way to explore a forum that has no search plugin'). It stops short of an explicit when-not or naming the alternative sibling tool, so it is strong but not fully prescriptive.

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, but the description adds non-obvious behavior: plugin-dependent accuracy, the inability to distinguish a question from a discussion in fallback mode, and conditional inclusion of triage status. Those degradations are exactly the semantics an agent needs to interpret results.

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

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

Three tight sentences, front-loaded with what the tool returns and progressively layering plugin conditions. No filler, though the closing triage sentence is somewhat dense and could have been its own clause rather than a trailing aside.

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 what comes back, and it does mention per-item triage status and the underlying candidate set. It still omits pagination behavior and any hint of result ordering, so it is solid but not exhaustive.

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 schema already documents page and the limit default of 20. The description adds nothing about pagination or result size, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('list unanswered questions') and frames the scope as 'the queue for someone who wants to help', which lets an agent distinguish it from search_forum, list_recent_topics, and find_answers 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?

Explains the two operational regimes: with the Q&A plugin it is the authoritative unsolved list, without it it falls back to recent unreplied topics. This tells the agent when results are trustworthy but stops short of naming a sibling tool to use instead when the approximation is insufficient.

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, but the description adds real behavioral context beyond them: the dependency on a search plugin, the fallback to title-only scanning of recent topics, and the fact that the tool announces when it is degraded. It does not cover rate limits or result-count behavior, but this is well above the annotation baseline.

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

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

Three sentences, front-loaded with the core capability, then the caveat, then the alternative. No sentence is redundant and every one 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?

No output schema exists, so the description correctly compensates by describing the return shape ('ranked matches with a snippet showing why each matched'). Combined with the fallback disclosure and sibling routing, an agent has everything required to call and interpret this tool.

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

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

Schema description coverage is 100% and every parameter carries its own description, so the baseline is 3. The description mentions ranked matches with snippets but adds no syntax or defaults for 'in', 'sort_by', or 'within_days' beyond what the schema already states.

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 ('Full-text search across topic titles and post bodies') and immediately distinguishes itself from the sibling find_answers. An agent can identify what this does and how it differs from alternatives 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?

Explicitly names the alternative ('For answering a question, prefer find_answers, which also extracts the answers') and gives the condition that selects it. It also documents the degraded-mode scenario, telling the agent when this tool silently behaves differently.

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