WindowsForum MCP Server

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

Annotations already mark the tool as read-only and non-destructive. The description adds useful behavioral context beyond that by defining exactly what 'health' means: status histogram, missing supplements, drifted approved cards, and generation run summary. This helps the agent predict what the tool reports without contradicting the 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?

The entire description is one dense sentence that front-loads the core purpose and then lists the key metrics in a dash-separated sequence. Every phrase contributes meaning, and there is no filler or repetition of the tool name or title.

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 parameterless read-only tool with an output schema, the description covers all essential context: what corpus it applies to, the aggregate nature of the data, and the specific metrics an agent can expect. No critical usage or behavior details are 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?

The tool has zero parameters, so the baseline is 4. There is no parameter detail needed, and the description correctly focuses on what the tool returns rather than input semantics.

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

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

The description states a specific verb ('Get'), a clear resource ('Key-Facts supplement corpus'), and enumerates four concrete outputs (status histogram, missing supplements, drifted cards, generation run summary). It distinguishes the tool as an aggregate health overview from sibling tools like list_drifted, but it does not explicitly name a sibling or state what this tool is not.

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 implies this is the right choice for high-level corpus health summaries rather than item-level listing or search, but it never explicitly states when to use this tool versus siblings such as supplement_status or list_drifted. An agent must infer the boundary from the word 'aggregate' rather than being told.

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 readOnly/non-destructive/closed-world, so the lower bar applies, and the description still adds real behavior: full post bodies, a 50-post cap on threads, and the truncation/pagination signals to inspect. The word "visible" hints at moderation filtering without explaining it, and no rate limits or auth are mentioned, keeping this 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?

Three short sentences: purpose first, return shape second, pagination escape hatch third. No filler, no restating of the title, and the most actionable detail (the continue-with call) is included verbatim as a signature.

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 explained, and the description covers the one non-obvious risk (truncated threads) with a concrete remedy. The remaining gap is sibling disambiguation among the many get_* tools, which matters given how crowded this namespace is.

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 single 'id' parameter is fully documented in the schema, including the thread-then-post fallback for plain numbers. The description adds nothing about the ID beyond what the schema already says, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ("Retrieve a WindowsForum document by ID") plus the purpose (analysis and citation), and clarifies the polymorphic return (posts in full, threads with 50 visible posts). It does not, however, distinguish itself from siblings get_thread and get_post, which appear to cover the same ground, so an agent still cannot tell from the description alone why to pick '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?

Gives explicit routing for the overflow case: check metadata.truncated / metadata.pagination and continue with get_thread_posts(thread_id, offset=next_offset). That is a concrete when-to-use-this-vs-alternative statement. It offers no guidance on when to prefer the dedicated get_thread/get_post tools over this generic fetch, which is the main ambiguity here.

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 destructiveHint=false. Description adds specific return fields (title, description, counts), slightly enhancing transparency without contradicting 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?

Single efficient sentence with primary action front-loaded. No filler; every word serves purpose.

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 a simple tool with one parameter, rich annotations, and output schema present, the description sufficiently explains what the tool returns and suggests companion tools for broader use.

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 covers 100% of parameter documentation with clear description. Description's 'by node id' adds no new meaning. 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?

Description specifies exact verb 'Get', resource 'WindowsForum forum section's details', and lists returned data (title, description, counts). Differentiates from siblings like get_forum_updates by noting it's for static details.

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?

Description advises pairing with list_threads or get_forum_updates for activity, providing usage context. Lacks explicit when-not-to-use or alternatives like get_forum_statistics but still helpful.

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 the safety profile is covered structurally. The description adds the useful behavioral detail that the result set is sitewide and includes both lifetime totals and same-day counters, though it says nothing about rate limits or freshness guarantees.

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 with the metric list front-loaded and the usage clause trailing. Every clause earns its place; there is no filler or restatement of the title.

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 an output schema present, the description need not document return values, and with rich read-only annotations plus zero parameters there is nothing else an agent needs. The description is complete for the scope of 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly avoids inventing filter arguments that the schema does not support.

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 ('Get') and resource ('sitewide WindowsForum statistics') and enumerates exactly what is returned: total threads, posts, members, plus today's thread and post counts. This distinguishes it from the aggregate-oriented siblings like corpus_stats and get_forum without the agent needing to open 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?

The phrase 'use for questions about the community's size and activity' gives a clear usage context, which is meaningful given the many sibling read tools. It stops short of naming an alternative (e.g. corpus_stats) or stating when-not to use it, so it does not reach a 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 indicate read-only, non-destructive. Description adds value by clarifying time window (last N hours) and scope (across community). No contradictions.

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

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

Single sentence with semicolon is concise and front-loaded. Every word adds value: verb, resource, time scope, and use case. No waste.

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 single parameter, high schema coverage, and presence of output schema, the description fully covers purpose, usage, and scope. Sibling list is large, but the description clearly differentiates.

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 already describes the 'hours' parameter with default and meaning. Description restates the default but adds no additional constraint info. Baseline 3 is appropriate.

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

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

Description states verb 'Summarize' and resource 'recent WindowsForum activity', explicitly calling out 'new threads and posts' and targeting 'what's new' questions. Distinguishes from siblings like get_forum_statistics and get_thread.

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?

Clearly specifies use case ('what's new' questions) with a default time window. No explicit when-not-to-use, but the guidance is sufficient for a simple 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 mark readOnlyHint and destructiveHint, so the description adds value by detailing the source (support.microsoft.com) and content returned (title, summary, affected builds, known issues, resolution steps). No contradiction.

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 two paragraphs, front-loading the core function and then providing usage guidance. Some redundancy exists (title/summary repeated), but it's concise overall.

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 tool with one parameter, output schema, and clear annotations, the description is complete enough. It covers the KB number format, content returned, and usage scenario. Minor omission: no mention of potential missing articles or rate limits, but not critical.

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 description for kb_id. The description adds examples like 'KB5063878' and clarifies that the 'KB' prefix is optional, enhancing the schema's information.

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 clearly states the tool retrieves a Microsoft KB article by KB number, specifying it returns title, summary, affected builds, and later mentions known issues and resolution steps. It distinguishes from siblings like search_kb by noting it is for specific KB numbers.

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 tool when a user asks about a specific KB number,' providing clear usage context. While it does not name alternative tools, the sibling list includes search_kb, implying its contrasting use case.

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 destructiveHint=false, so the main safety profile is covered. The description adds meaningful behavioral context by specifying that only confirmed, non-banned accounts are listed, matching the forum's own 'New members' list. This clarifies the filtering behavior beyond 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?

The description is compact and front-loaded with the main purpose; the second sentence adds important filtering context. Every sentence earns its place with 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?

Given the single optional parameter, complete schema coverage, read-only annotations, and the existence of an output schema, the description provides all necessary context: what the tool returns, who is included/excluded, and when to use it. Nothing critical 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?

The only parameter, 'limit', is fully documented in the schema with a clear description and default value (schema coverage 100%). The description does not add parameter-level detail, but none is needed since the schema is complete. Baseline 3 is appropriate.

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

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

The description states a specific verb ('List'), a precise resource ('newest WindowsForum member registrations'), and the intended use cases ('community-growth questions' or 'identify recent joiners'). This clearly differentiates it from sibling tools like get_online_users, get_user, and search_users.

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 gives clear context for when to use the tool ('community-growth questions' or 'identify recent joiners'). It does not explicitly mention exclusions or alternatives, but the stated purpose is sufficient for an agent to select it appropriately among the sibling 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 cover the safety profile (readOnlyHint, non-destructive, closed-world), so the description earns credit for adding behavior: a 15-minute activity window, a member/guest/robot breakdown, and the caveat that only members who display online status are named. That last detail materially sets expectations about coverage.

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?

One front-loaded sentence that leads with the purpose, then qualifies scope in a single clause. 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?

For a no-argument snapshot tool with an output schema already defining return values, the description covers what is read, over what window, and at what granularity. 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly avoids inventing or implying any filtering inputs.

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 ('See who is on WindowsForum right now') plus the exact scope (members, guests, robots in the last 15 minutes). It is clearly distinguishable from siblings like get_latest_registered_users or get_forum_statistics.

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 phrase 'right now' implies this is a live-snapshot tool, which is enough to suggest when it applies. However, it names no alternative (e.g. get_latest_registered_users, render_community_overview) and gives no when-not-to-use guidance, so routing must be inferred.

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 destructiveHint=false, so the description does not need to repeat safety info. It adds value by detailing return fields (text, author, thread context, URL), providing behavioral context beyond the 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?

The description is a single efficient sentence covering action, resource, identifier, return data, and usage hint, with no wasted words.

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 only one parameter and an output schema present, the description adequately covers what the tool does, how to use it, and when to use it, leaving no significant gaps.

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

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

Schema coverage is 100%, and the schema already describes post_id as 'The post ID to retrieve.' The description only restates 'by post id' without adding format or constraints, so baseline 3 is appropriate.

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

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

The description clearly states the verb (Get), resource (single post), and identifier (by post id). It lists return fields (text, author, thread context, URL), distinguishing it from sibling tools like get_thread_posts or get_thread.

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 explicitly states when to use: 'use when you have a specific post reference to verify or quote.' It implies alternatives if no specific reference exists, but does not explicitly list when not to use.

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 annotations (readOnlyHint=true), the description details the returned fields and emphasizes metadata-only nature, adding 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?

Single concise sentence with clear function, output specification, and usage guidance. No wasted words.

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?

Fully adequate for a simple tool with annotations, output schema, and clear sibling differentiation. No gaps.

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

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

Schema coverage is 100% with a clear description for thread_id. The tool description adds no further parameter details, but the single integer ID is straightforward, so baseline 3 is appropriate.

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

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

The description clearly states it retrieves thread metadata by ID, listing specific fields (title, author, counts, dates, URL). It distinguishes from siblings like fetch and get_thread_posts for content retrieval.

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 directs agents to use fetch or get_thread_posts for content, providing clear context for when to use this tool vs alternatives.

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

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

Annotations already establish readOnlyHint/destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: results are restricted to 'visible' posts (implying hidden/deleted content is filtered), ordering is oldest-first, later replies and accepted solutions are included, and continuation depends on pagination.has_more.

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, zero filler, with the scope/filtering constraint front-loaded and the pagination instruction following. Every clause carries information.

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

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

With an output schema present, return-format explanation is unnecessary, and the annotations cover safety. The description suffices for correct invocation, though it leaves the meaning of 'visible' and the relationship to search_posts/render_thread 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% (limit, offset, thread_id all documented), so baseline is 3. The description adds nothing about parameter syntax or interaction (e.g., how offset relates to pagination.next_offset) 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?

Names a specific verb and resource ('Read a page of ... posts in a WindowsForum thread') plus scope ('oldest first'), which cleanly separates it from get_post (singular) and get_thread (metadata). It does not, however, name a sibling or state what it is not, so full sibling differentiation relies on inference.

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 operational guidance ('Follow pagination.next_offset while pagination.has_more to read the full conversation'), which is really how-to-paginate rather than when-to-use. There is no statement telling the agent to prefer search_posts or get_thread instead under any condition.

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 readOnlyHint=true, openWorldHint=false, and destructiveHint=false, and an output schema exists for return values. The description adds that the time is server-side and frames it as a pre-search anchor, but does not disclose timezone, precision, or any other behavioral nuance. With safety and returns covered elsewhere, this is adequate but not rich.

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 front-loads the purpose and then adds the usage cue. Every clause earns its place; there is no redundant or vague text.

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 tool with rich annotations and a separate output schema, the description covers what the tool returns and when to call it. Nothing needed 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?

The tool has zero parameters, so the baseline is 4. There is no parameter information to add, and the description correctly does not fabricate any parameter semantics.

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

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

The description states a specific verb and resource: 'Get the current server date and time.' It is trivially distinguishable from all sibling tools, which deal with content retrieval, rendering, or search rather than exposing the current server time.

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

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

It explicitly advises use 'to anchor time-sensitive queries like "latest" or "this week" before searching recent content,' giving a clear when-to-use context. It does not name alternatives or exclusions, so it falls short of a full 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 and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: what a signed-out visitor would see, profile-limited members getting username-only results, and last seen being omitted when online status is hidden.

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 compact, front-loaded with the core purpose, and each sentence earns its place. It avoids filler while still covering the essential behavior.

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-parameter read-only tool with an output schema, the description is complete. It covers the lookup key, the returned profile fields, and the important privacy-driven output variations, leaving nothing an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, with the identifier parameter described as 'Username or user ID'. The description repeats the same meaning without adding extra format, case-sensitivity, or ambiguity guidance, so it stays at the baseline for fully documented 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?

States a specific verb ('Look up'), a clear resource ('a WindowsForum member's public profile'), and exact lookup keys ('by username or user id'). The listed returned fields and the exact-identifier semantics make it easy to distinguish from sibling search/list tools such as search_users or get_latest_registered_users.

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 implies the intended use: retrieve a public member profile when you have an exact username or user id. It does not explicitly state when not to use it or point to alternatives like search_users, though the visibility caveat provides some context about limitations.

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 destructiveHint=false, indicating safe read-only behavior. The description adds context about the time window (last N days), default value of 7, and the curated nature of the news threads, which goes beyond annotations to set expectations on the scope and nature of 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?

The description is a single concise sentence that efficiently conveys the source, time range, default, and content type. No redundant words, well-structured.

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 tool's simplicity (single parameter, with output schema present), the description is complete. It sets clear expectations for what the tool returns and the parameter meaning. The output schema likely handles return structure.

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% with a clear description for the single parameter 'days'. The tool description repeats the default value, adding no new semantic information. Baseline score of 3 is appropriate as schema already covers parameter meaning.

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 clearly states it retrieves recent Windows news coverage from WindowsForum, specifying the content type (curated news threads on updates, security patches, and Microsoft announcements). This specific verb+resource combination distinguishes it from sibling tools which handle general forum content or search.

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 implies this tool should be used for Windows news, but it does not explicitly state when not to use it or mention alternatives among siblings. The context of sibling tools provides implicit guidance, but explicit usage guidelines are missing.

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

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

Annotations already mark the tool as readOnly and non-destructive. The description adds meaningful behavioral context by explaining the drift mechanism and the 'dark card' state, which is not derivable from the annotations or schema. It does not describe pagination or sorting behavior, but the output schema likely covers return structure.

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

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

Two sentences carry the core purpose, the triggering condition, and the operational context without any filler. The key differentiator is front-loaded, making it easy for an agent to scan and select correctly.

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 read-only list operation with one optional parameter, a rich output schema, and full annotation coverage, the description provides everything needed. It explains what the tool returns, why these threads matter, and how they are identified. No critical gap remains.

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 only parameter is `limit` with a clear default and range. The description adds no extra parameter semantics, but it doesn't need to because the schema fully documents the single optional parameter. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: list article threads with a dark Key-Facts card caused by content-hash drift after an opening-post edit. This clearly distinguishes it from sibling tools like list_threads and search_threads, which do not target this specific drifted state.

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 gives clear context for when this tool is relevant: when identifying threads whose approved Key-Facts card is dark because the opening post changed after approval. It also notes these are exactly what the hourly fill driver repairs next, which implies operational selection. It stops short of explicitly naming alternatives or stating when not to use it.

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 destructiveHint=false, establishing safety. The description adds behavioral context: it returns items in newest-first order, supports multiple content types (threads, news, tutorials), and implies no search filtering. It does not describe pagination or result limits beyond the schema parameters, but the openWorldHint=false adds context that results are from a closed set. Overall, adds useful context beyond 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 sentences with zero waste. The primary purpose and usage condition are front-loaded, followed by a directive on how to render results. Every phrase adds value.

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 list tool with 3 optional parameters fully documented in the schema, an output schema present, and clear usage guidance, the description is complete. It covers when to use, what it returns (newest items), how to display results, and the absence of search. An agent can call it correctly without further info.

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 parameters are fully documented in the schema. The description adds value by clarifying the 'section' parameter's meaning ('tutorials' for latest tutorials, etc.) and reinforcing that no search query is involved. It goes slightly beyond the schema by implying default behavior and common use cases, but doesn't introduce new details about limit/offset formatting.

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 clear verb ('List'), resource ('newest WindowsForum threads, news articles or tutorials'), and ordering ('newest first'), distinguishing it from search tools. However, it doesn't explicitly name a sibling or contrast with similar list tools (e.g., get_forum_updates), so differentiation is slightly less precise than ideal.

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 usage guidance: 'use when the user asks for the latest, newest or most recent tutorials, news or threads' and states it's for no search query, distinguishing from search tools. It also instructs to pass item `id` to render_search_results for display, giving clear action 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, which covers the safety profile. The description adds the output contents (like 'who is online now' and 'latest threads') but does not disclose any further behavioral traits such as data freshness, aggregation behavior, or rendering format.

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: the first defines the tool's purpose and output, the second gives usage guidance. No redundancy or filler, and the main action is 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?

For a zero-parameter tool with no output schema, the description adequately lists what is displayed and when to use it. It does not describe the card's visual structure or refresh behavior, but those are not essential for correct invocation given the tool's simplicity.

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 has zero parameters and the schema is empty (100% coverage). The description correctly does not need to explain parameters, matching the baseline of 4 for parameterless tools.

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 clearly states the tool renders a community overview card and lists its contents (threads, posts, members, online users, latest threads). It is specific about the resource, but it does not explicitly name sibling tools or contrast with options like get_forum_statistics or get_online_users, so it stops short of full sibling differentiation.

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

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

The tool gives clear usage context: 'Use for questions about the community's size or current activity.' However, it does not state when not to use it or point to alternatives, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by specifying that the article is rendered as a card with only title, highlights, and link, rather than full article content.

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 concise sentences earn their place: the first explains what the tool does and its output format, the second states the invocation condition. No redundant or vague wording.

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 tool has a single parameter, full schema coverage, and annotations covering the read-only nature. The description supplies the expected card presentation. For a low-complexity rendering tool, nothing essential 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% and the single kb_id parameter is fully documented with format examples. The description's mention of 'a specific KB article' aligns with the parameter but adds no new semantic 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?

The description states a specific verb ('Show') and resource ('official Microsoft Knowledge Base article'), and describes the output form: 'a card with its title, highlights, and link to support.microsoft.com.' This differentiates it from siblings like get_kb_article, which likely fetches raw article data rather than rendering a user-facing card.

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 includes a clear usage trigger: 'Use when the user asks to see a specific KB article.' It does not explicitly mention exclusions or alternatives such as get_kb_article or search_kb, so it falls just short of a 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 and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail: it renders a card grouped by section, displays title, snippet, author, date, and link, and preserves the order of passed ids. This is beyond the annotations and helps the agent understand the output behavior.

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 no fluff. Purpose is front-loaded, workflow follows logically, and the display details are concise. 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 rendering tool with read-only annotations and no output schema, the description covers the main workflow, display contents, and ordering. It could mention what happens with invalid ids or explicitly state it does not search, but the 'call search first' instruction covers that. Overall complete for the agent's needs.

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 both parameters have clear descriptions. The description reinforces the ids parameter as document ids to display and mentions order preservation, but adds little beyond the schema. It also references the query as the card heading, which is already in the schema. Baseline of 3 is appropriate given high schema coverage.

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?

Description states a specific verb ('Show') and resource (threads, news, tutorials, posts as a result card), and implicitly distinguishes from sibling render tools like render_thread and render_kb_article by focusing on a grouped result card. It clearly conveys what the tool does.

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 prescribes the workflow: call search or list_threads first, select relevant results, preserve order, then pass ids. This gives clear when-to-use guidance and implies it is for displaying multiple search results, not for individual rendering. It names the prerequisite tools directly.

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 destructiveHint=false, so the description is consistent. It adds context beyond those annotations by specifying the presentation behavior ('readable card'), which is useful for an agent to understand the output format. It does not contradict the 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?

The description is two concise sentences with no filler. The main purpose is front-loaded, and the usage guidance follows immediately. 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 simple read-only tool with a single well-documented parameter and no output schema, the description fully covers what the agent needs to know to invoke it correctly. It includes when to use it and what it does, leaving no critical gaps.

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

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

The schema provides a complete description for thread_id (type, example), achieving 100% coverage. The tool description adds no additional parameter guidance beyond what the schema already includes, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool shows a WindowsForum thread as a readable card with opening post and replies, which is a specific verb+resource+format. It distinguishes from sibling tools like get_thread by emphasizing the presentation aspect ('readable card') rather than raw data retrieval.

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 explicitly instructs to use this tool after search or fetch when the user wants to see or open a specific discussion. It provides clear context for when to invoke it, though it does not explicitly mention alternatives or exclusions, so it stops short of a 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 and openWorldHint=false, so safety is covered; the description adds real context beyond that by describing the return shape ('list of search results with basic information'), the downstream handoff to render_search_results, and the fetch follow-up for long threads. It stops short of pagination or rate-limit behavior, so it is strong but not 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?

Purpose and default-behavior rules are front-loaded in the first three sentences, with return/chaining information after. Slightly redundant with the schema's own section/sort descriptions and the final 'Returns a list...' sentence repeats itself, but overall it is tight and skimmable.

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 5-parameter read-only search tool with a 100% documented schema and an output schema, the description covers everything the agent must decide: when to use it, default parameter choices, and the follow-on tools (render_search_results, fetch). Nothing needed for a correct call 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 includes enum explanations for section and sort, so the schema already carries parameter meaning. The description reinforces the defaults and intentions ('keep section all', 'set sort=newest') but adds no format, syntax, or constraint detail the schema lacks — 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 ('Search all WindowsForum content') plus the scope covered (threads, news, tutorials) and the ranking method (combined keyword and semantic). It also positions itself against the many search_* siblings by claiming 'the best first call for any question or topic', so an agent can differentiate 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?

Gives explicit conditional guidance: keep section='all' unless the user asks for one kind of content, use sort='newest' for latest/newest requests, and pass result ids to render_search_results. It also names an alternative for deeper content ('Use the fetch tool for document content and continuation details for long threads'), which is exactly the when/when-not routing an agent needs.

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 destructiveHint=false, so safety is covered; the description adds genuine operational behavior — exact totals only when total_relation is 'eq', otherwise a lower bound, and the instruction to narrow rather than page when pagination_limited is true. Some of this overlaps output-schema fields (has_more, next_from), but the guidance on how to act on them is beyond what the schema conveys.

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 first sentence is well front-loaded and information-dense. However, the trailing paragraph 'Complements the main `search` tool: use this to page through a large result set with an explicit offset' restates the opening sentence almost verbatim, adding length without new information.

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

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

With annotations covering safety, a full output schema, and 100% parameter documentation, the description only needs to add routing and pagination behavior, which it does. The one residual gap is not distinguishing itself from the other search-flavored siblings, but 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% with clear per-parameter docs, including the size/limit alias, from_/next_from continuation, and section enum semantics, so the baseline is 3. The description adds only the general notion of offset paging and section narrowing, not new syntax or format 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 specific verb and resource ('Relevance-ranked full-text thread search') plus its distinguishing capability ('explicit offset pagination'), and explicitly positions it against the sibling `search` tool. An agent can tell it apart from `search`, `search_threads`, and `search_posts` 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?

Gives clear when-to-use: page through a large result set beyond what the main search tool returns, and names that alternative explicitly. It also gives a when-not condition ('if pagination_limited is true, narrow the query or section instead of paging further'). It does not, however, distinguish itself from other search siblings such as search_threads or search_semantic.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false). The description adds non-obvious behavior: results are returned newest-first and include titles, release dates, and support.microsoft.com URLs. It stops short of noting result-count limits or paging behavior, but the ordering guarantee is a genuinely useful addition.

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. Scope and when-to-use lead, and the fallback to get_kb_article closes. Every clause carries information an agent needs for selection.

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 re-explained, and the description still summarizes shape and ordering. Scope, usage condition, alternative, and query forms are all present for a two-parameter read tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by enumerating acceptable query forms (topic, keyword, build, or KB number), which tells the agent it can pass '24H2' or 'KB5034441' as a query — semantic guidance the schema only hints at via one example.

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 (Search) plus a tightly scoped resource (official Microsoft KB articles for Windows 10/11/Server updates) and the queryable axes (topic, keyword, build, KB number). It is immediately separable from the sibling get_kb_article, which fetches a single article rather than searching.

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 when-to-use clause: 'use for Windows update, patch, and known-issue lookups when you lack a KB number.' It also names the alternative (get_kb_article) and the condition that selects it, so the routing decision is fully specified.

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 provide readOnlyHint=true and destructiveHint=false, lowering the burden. The description adds useful behavioral context: matching is exact substring, and results are ordered by view count. It does not mention pagination or rate limits, but for a read-only search tool with an output schema this is sufficient additional disclosure.

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 first sentence conveys the full substance: exact substring lookup, target fields, ordering, and the contrast with relevance-ranked search. The second sentence repeats the same 'literal vs relevance-ranked' contrast and the relationship to `search`, adding no new information. This redundancy means not 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?

Given the 100% schema coverage, safe read-only annotations, and presence of an output schema, the description provides adequate context: what is searched, matching semantics, ordering, and when to prefer this tool over `search`. Nothing critical for correctly invoking the tool appears to be 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 schema already provides rich, self-explanatory descriptions for `query`, `limit`, and `section`. The tool description's mention of exact substring matches `query` and adds no parameter-level meaning beyond what the schema already documents. Baseline 3 applies.

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

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

The description states a specific operation ('Exact substring lookup over thread titles and author usernames'), names the ordering ('ordered by view count'), and contrasts itself with relevance-ranked full-text search. This makes its purpose immediately clear and distinguishes it from the sibling `search` tool without needing to inspect schemas.

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

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

The description explicitly says to use this tool for literal title/author matching rather than relevance-ranked full-text search and names `search` as the complementary alternative. It is clear about the primary decision, though it does not distinguish from other search siblings like `search_threads` or `search_users`. The core usage guidance is present.

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

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

Annotations already mark the tool as read-only and non-destructive, covering the safety profile. The description adds meaningful behavioral context by specifying the search scope (individual post content, not titles) and the intended purpose. It does not disclose pagination or matching semantics, but the output schema covers return structure, so the additional context is sufficient.

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?

One sentence of about 29 words, front-loaded with the action ('Search individual WindowsForum posts') followed by a pragmatic use case. No filler, no repetition, and 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 a complete input schema, an output schema, and read-only annotations, the description only needs to convey purpose and selection context, which it does. It distinguishes from thread-title search but not from the other search siblings (search_elastic, search_mysql, search_semantic), leaving some ambiguity among the wider tool set.

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%, with the section parameter's enum values and usage guidance already fully explained in the schema. The description's phrase 'keyword or phrase' loosely maps to the query parameter but adds no new parameter-level information. Baseline 3 applies because 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 states a specific verb ('Search'), a specific resource ('individual WindowsForum posts'), and explicitly contrasts with 'not just thread titles', distinguishing it from sibling search_threads. It also names the use case (answers, error messages, fixes buried in long threads), making the tool's purpose unambiguous.

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

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

It gives an explicit when-to-use cue: 'use to find specific answers, error messages, or fixes buried inside long threads.' The phrase 'not just thread titles' implies a contrast with thread-title search, but it never names an alternative tool or states when not to use it, so it falls short of a full 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 and destructiveHint=false, so the safety profile is covered. The description adds the kNN vector similarity mechanism and the fact that results may not share exact keywords, which is useful behavioral context. However, it doesn't disclose details like result ordering, pagination, or potential latency, which would be valuable for a semantic search tool.

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 concise and front-loaded with the core purpose. The first sentence states what the tool does, and the second paragraph explains the mechanism. It's slightly redundant with the title and the schema's section description, but overall it's efficient and well-structured.

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 output schema exists and annotations cover the safety profile, the description is fairly complete. It explains the semantic search mechanism, when to use it, and the section parameter's behavior. It could mention result ordering or how it differs from search_elastic, but for a read-only search tool with a rich schema, this is adequate.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the conceptual framing of 'query' as a natural language query and the section parameter's guidance about keeping 'all' for questions, which is helpful. But the description doesn't add significant meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: finding WindowsForum discussions by meaning rather than exact words, using embedding-based semantic search. It explicitly distinguishes itself from keyword-based search by emphasizing natural-language questions and paraphrased topics, which differentiates it from sibling tools like search, search_elastic, and search_mysql.

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 provides clear context for when to use this tool: best for natural language questions and conceptual searches. It doesn't explicitly name alternatives or state when not to use it, but the contrast with exact-keyword search is implied. The section parameter description adds practical guidance on when to use specific values, which helps an agent decide.

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/safe/closed-world, yet the description adds substantial non-obvious behavior: short-lived cursors (<2 min), the frozen popularity snapshot, source-aggregated ~15-minute view cadence, total_relation semantics, and pagination_limited handling. This is real operational context an agent cannot get from 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?

The purpose and the 'use when' clause are front-loaded, and most sentences carry actionable information. It is dense and leans on internal jargon ('database transaction barrier', 'rolling metadata sweep') that may not help an agent, keeping it just below the top mark.

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 a full output schema and safe annotations, the description covers the remaining gaps: ordering overrides, cursor lifetime, count freshness/watermarks, total_relation bounds, and how to react to pagination_limited. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely extends the schema: it explains the popularity continuation flow (pass next_cursor as cursor with from_=0, same query/section/sort), the latest/newest override of relevance sort, and the practical meaning of order/sortby combinations.

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

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

The opening states a specific verb+resource ('Search WindowsForum threads') and enumerates the sortable dimensions and pagination, so the agent knows exactly what this does. It does not, however, distinguish itself from the many sibling search tools (search, search_posts, search_semantic, search_elastic), leaving that routing to the tool name alone.

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

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

It gives a clear when-to-use signal ('use when result ordering or paging matters') plus concrete query-pattern guidance ('latest tutorials' lists that section without requiring those words). It stops short of naming alternative tools or stating when-not to use it, so it is context-rich but not 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 destructiveHint=false, so description adds limited behavioral context (e.g., matches usernames). Does not disclose query behavior like partial matching or pagination, but not contradictory.

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

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

Single sentence that efficiently conveys purpose and usage. No redundant information.

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

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

Given the simplicity of the tool (2 params, 1 required) and existence of an output schema, the description is largely sufficient. Could mention limit default behavior, but not essential.

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 descriptions for both parameters. Description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

Clearly states verb 'Find' and resource 'members whose usernames match a query'. Differentiates from sibling tools like get_user and other search tools by specifying it's for locating a member before fetching full profile.

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 workflow: use this to locate a member before calling get_user. However, it does not mention alternatives like search_posts or when not to use 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 readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by detailing the lifecycle values, the notion of a live 'current' revision, and the 'dark' state caused by edits after approval. It does not contradict the 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 sentences with no filler. The first sentence front-loads what the tool returns, and the second gives a concrete diagnostic use case. Every clause adds useful information.

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

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

The tool has a single required parameter, safe read-only annotations, and an output schema that can carry the return-structure details. The description provides the diagnostic scenario, explains the meaning of 'dark', and covers all state categories an agent needs to decide whether to call this tool. Nothing essential 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 thread_id is adequately documented as 'XenForo thread ID'. The description reinforces that it targets 'one article thread' but adds no essential parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Get'), a specific resource ('Key-Facts supplement state for one article thread'), and enumerates the exact facets of that state: lifecycle status, current-revision flag, and sidebar rendering/dark/absent. This clearly differentiates it from broad list/search siblings like list_drifted or get_thread.

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 explicitly tells the agent when to use it: 'Use to answer "why is there no Key-Facts card on thread N?"'. This is a clear invocation context, though it does not explicitly state when not to use it or name alternative tools for comparison.

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