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

With no annotations, the description carries the full burden. It discloses the return format (JSON with results and meta), including pagination fields (page, limit, has_more), and explains the query syntax thoroughly. It does not explicitly state side effects or permissions, but the read-only nature is strongly implied by 'filter' and the output 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?

The description is appropriately sized. The opening sentence states the core purpose, the second sentence covers the return format, and the remainder compactly lists query syntax options. Every sentence provides necessary information, and the structure is easy to scan despite its length.

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 complex query language and no output schema, so the description must compensate. It does so by specifying the exact return shape (results array with id, slug, title; meta with page, limit, has_more) and covering the major query facets: category, tag, status, in, date, and order. This makes the behavior of the tool understandable without additional schema information.

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%, but the description goes far beyond by detailing the entire query language syntax, including operators for categories, tags, status, in-options, date filters, and ordering. This adds substantial meaning beyond the schema's simple example and parameter descriptions.

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 filters topics using a concise query language, and it distinguishes itself from siblings like discourse_search by describing the specific filtering capabilities and output format. The verb 'filter' and resource 'topics' are explicitly named, making the 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?

The description implies when to use this tool—when you need to filter topics by categories, tags, status, date, or ordering—and provides a detailed query syntax. However, it does not explicitly contrast with alternatives like discourse_search or state when not to use it, so clear context is provided but exclusions are absent.

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?

There are no annotations, so the description carries full responsibility for behavioral disclosure. It reveals the return object structure but does not mention pagination behavior, how parameters like direction or target_date interact, authentication requirements, or that it is a read-only operation. The description adds minimal behavioral context beyond the action verb.

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 short sentences, front-loaded with the primary action and scope, followed by a concise breakdown of the return structure. There is no wasted 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 5 parameters, no annotations, and no output schema, but the description only explains the return structure. It does not clarify pagination semantics, defaults, or how to combine direction, target_date, and target_message_id. The description is not rich enough for the tool's complexity, even with the schema providing parameter descriptions.

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 all five parameters documented. The description adds no parameter-level detail beyond what the schema already provides, 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?

The description clearly states the tool gets messages from a chat channel, specifying the resource and action. However, it does not explicitly differentiate from sibling tools like discourse_read_topic or discourse_get_query, though the chat channel scope implies distinction.

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?

No guidance is provided on when to use this tool versus alternatives. The description only states what it does, not when it should be preferred, nor does it mention any exclusions or 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?

With no annotations, the description carries the burden of behavioral disclosure. It states the operation is a read ('Retrieve') and describes the response format, which is useful. But it omits details like error behavior, authentication requirements, or whether the sequence parameter is validated. This is acceptable 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?

The description is one sentence, front-loaded with the action and target, and includes a compact list of return fields. 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?

For a simple read tool with 2 parameters and no output schema, the description covers the essential aspects: what it does, what input it takes (via schema), and what it returns. It doesn't document edge cases, but the tool is straightforward enough that this is not a significant 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 description coverage is 100%, so both parameters are already well-documented in the schema. The description adds little beyond restating that the draft is retrieved by key and referencing the returned fields. The baseline of 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 uses a specific verb ('Retrieve') and resource ('specific draft by key'), clearly distinguishing it from sibling tools that handle users, topics, queries, etc. It also previews the returned fields, making the tool's scope 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?

The description implies usage: when you need a draft by its key. It provides clear context on what the tool does, but does not explicitly mention when not to use it or name alternatives. However, no sibling tool deals with drafts, so this is adequate.

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?

With no annotations, the description carries the burden of disclosing behavior. It mentions the admin API key requirement, which is useful auth context, and 'Get' implies a read-only operation. However, it does not explicitly confirm non-mutating behavior, describe error handling, or detail the response structure beyond SQL and parameters.

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 sentences with zero filler. It front-loads the core purpose and includes a critical prerequisite (admin key) without 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 simple single-parameter GET tool with no output schema, the description adequately covers the return content (SQL and parameters) and an access constraint. It is thorough enough for an agent to select and invoke correctly, though it omits potential error behaviors or response format details.

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 already provides 100% coverage with a description for the 'id' parameter ('Query ID'), and the description adds context by specifying it's a Data Explorer query ID and that details include SQL/parameters. This adds marginal value beyond the schema but does not fully compensate since the parameter meaning is straightforward.

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 action ('Get full details') and resource ('Data Explorer query'), and specifies the scope ('including SQL and parameters'). This distinguishes it from sibling tools like discourse_run_query, which executes queries rather than retrieving their definitions.

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 is for retrieving query metadata rather than executing it, and the admin API key requirement provides context for when it can be used. However, it does not explicitly state when not to use it or mention alternative tools, though the sibling discourse_run_query clearly serves a different purpose.

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?

With no annotations, the description carries the full burden. It lists the return fields, which provides some transparency, but it omits error handling, authentication requirements, and an explicit statement that this is a read-only operation. The added behavioral context is partial.

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: two sentences with the action front-loaded. It lists the returned fields efficiently without unnecessary detail, making it easy to scan.

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

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

For a simple one-parameter read tool, the description covers the return fields but lacks mention of the required parameter, error behavior, and usage context. It is marginally adequate but leaves gaps that the agent would need to resolve.

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

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

Schema description coverage is 0%, and the description does not mention the 'username' parameter at all. The parameter name and tool name imply its meaning, but the description fails to connect the parameter to the tool's function, so it adds no meaningful semantic value.

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 user info and enumerates the returned fields, distinguishing it from siblings like discourse_list_users by implying a single-user lookup. The verb 'Get' and resource 'user info' are specific and 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?

No guidance is provided on when to use this tool vs alternatives like discourse_list_users or discourse_search. The description does not mention selection criteria, prerequisites, or exclusions, leaving the agent to infer usage from the name.

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?

No annotations are provided, so the description must carry the full burden. The verb 'Get' implies a read-only operation, and the return structure is disclosed (posts array and meta). However, it does not explicitly state side effects, authentication needs, or that it never modifies data, which is a minor gap.

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 sentence that front-loads the core action and includes a concise summary of the return shape. No filler or unnecessary 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?

For a simple list tool with no output schema, the description adequately explains what is returned and the pagination structure. It lacks details on ordering or filtering, but given the low complexity (3 params, no nested objects), it is sufficiently complete.

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

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

Schema coverage is only 33% (only limit is described). The description adds context by mentioning pagination and the meta fields (page, limit, has_more), but it doesn't explain the username or page parameters beyond their names. It provides marginal value but does not fully compensate for the schema gaps.

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 'Get paginated list of user posts/replies' with a specific verb and resource, which distinguishes it from sibling tools like discourse_list_users (lists all users) and discourse_read_post (reads a single post).

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 use case (listing a user's posts) clearly, but it does not explicitly mention alternatives or when-not-to-use. Since the context is obvious and no exclusions are needed, it earns a 4.

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?

With no annotations, the description carries the burden. It discloses the auth requirement (admin API key), pagination behavior (~100 users per page), and response structure (JSON with users array and pagination meta). It does not cover potential errors or rate limits, but the provided details are meaningful.

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, front-loaded with the purpose, and each sentence provides useful information: admin API requirement, fixed page size, and response format. 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?

For a list tool with 5 parameters and no output schema, the description covers the essential behavioral aspects (pagination, response format, auth). It does not explain retry behavior or error handling, but these are not critical for a simple list endpoint.

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 descriptions cover all 5 parameters (100% coverage) with definitions, defaults, and enums, so the description adds no parameter-specific meaning. Baseline of 3 is appropriate since 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 the specific action 'List users' and the resource via 'admin API', clearly distinguishing from sibling tools like discourse_get_user (which retrieves a single user) and discourse_list_user_posts (which lists a user's posts). It also mentions the response format, reinforcing scope.

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 by stating 'Requires admin API key', implying it is for admin-level user listing. It does not explicitly name alternatives or state when not to use it, but the admin requirement and the plural 'users' offer reasonable 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It voluntarily states that it 'Does not rotate browser profiles; uses the same authenticated HTTP client as other tools,' which is valuable context about side effects (none) and auth. It also discloses the output format (base64 + mimeType). It does not discuss failure modes, but for a read-only fetch, this is adequate.

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 three sentences, front-loaded with purpose, and contains no filler. Each sentence provides distinct value: what it does, what it returns, and usage context. It is compact and to the point.

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

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

There is no output schema, so the description appropriately explains the return value (MCP image content + text summary). It also covers the key context: when to use (after post/topic reads), what to pass, and the authentication behavior. It does not explain edge cases or error handling, but given the tool's simplicity and the schema's parameter details, it is sufficiently complete.

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 already covers 100% of parameter descriptions, so the baseline is 3. The description adds minimal extra parameter semantics beyond restating the url formats and the 'and/or' relationship, which is already evident from the schema's optional fields. No new meaning is introduced beyond what the schema provides.

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

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

The description starts with 'Fetch Discourse post images for the model to view,' which uses a specific verb (fetch) and resource (Discourse post images), clearly distinguishing it from siblings like discourse_read_post or discourse_read_topic. It also specifies the return type (MCP image content), leaving no ambiguity about the tool's function.

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: 'Use after discourse_read_post/topic when raw contains .' This tells the agent exactly when to invoke this tool relative to sibling tools. It also explains how to use parameters ('Pass url ... and/or post_id'), though it does not explicitly state when not to use it or offer alternatives, so it falls 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It correctly identifies this as a read operation and lists the exact JSON fields returned. However, it omits any mention of error conditions, permissions, or potential side effects, which would be expected for full transparency.

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, focused sentence. It is front-loaded with the primary purpose and wastes no words, making it highly concise 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?

Although the tool is simple, the description provides enough context for a basic read operation: it states the resource type, the key input, and the format of returned data. With no output schema, listing the returned fields is helpful. It falls short only in not mentioning any edge cases or error scenarios, but given the tool's simplicity, this is acceptable.

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

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

Schema description coverage is 0%, so the description should compensate by explaining the post_id parameter. However, it merely says 'a specific post' without explicitly stating that post_id identifies the post. The parameter name in the schema does the heavy lifting, but the description adds no semantic value beyond what is already obvious.

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 action ('Read a specific post') and identifies the resource (a post). It distinguishes itself from sibling tools like discourse_read_topic by focusing on a single post. The mention of returned fields adds specificity.

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?

No guidance is provided on when to use this tool versus alternatives. It does not mention exclusions or explicitly contrast with sibling tools. The purpose implies you need a post_id, but no contextual usage hints are given.

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 are absent, so the description carries full behavioral burden. It discloses the return format (JSON with specific fields) but omits handling of large topics, pagination defaults, or post array structure. Some transparency is provided, but deeper behavioral context is missing.

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 sentences, direct, and front-loaded with the main purpose ('Read topic metadata and posts') followed by return details. No unnecessary words or repetition.

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 3 parameters, no output schema, and no annotations, the description covers basic purpose and output fields but omits pagination behavior, post array details, and any context about topic_id. It is moderately complete but leaves gaps that could affect 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 67% (post_limit and start_post_number have descriptions), but the tool description adds no parameter semantics. It does not mention how to specify a topic or pagination behavior, leaving the agent reliant on the schema alone. Since coverage is not high, the description should compensate more.

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 uses a specific verb ('Read') with a clear resource ('topic') and explicitly states what is returned (metadata and posts). This distinguishes it from sibling tools like discourse_read_post (which likely targets a single post) and discourse_filter_topics (which filters topics).

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 no guidance on when to use this tool versus alternatives like discourse_read_post or discourse_search. It does not mention prerequisites, exclusions, or typical use cases, leaving the agent without explicit decision support.

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?

With no annotations, the description carries the full burden and discloses important behavioral traits: read-only transactions, 10-second timeout, admin API key requirement, and the return fields. This adds meaningful context beyond the schema, though it stops short of describing all edge cases like error handling.

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

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

Two sentences, front-loaded, every clause earns its place. The description efficiently covers purpose, return format, safety, timeout, and authorization without 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 tool's complexity (4 params, nested objects, no output schema), the description provides sufficient context: return shape, execution constraints, and auth. It could enumerate more behavioral details, but the schema covers parameter semantics well.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already provides, but it doesn't need to since all parameters are well-documented.

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 executes a Data Explorer query with parameters, using specific verbs and defining the resource. It distinguishes from siblings like discourse_get_query by focusing on execution, though it does not explicitly name alternatives.

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

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

No explicit when-to-use or alternative guidance is provided. The purpose implies usage but there is no context about choosing this over other tools, prerequisites beyond admin API key, or 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?

The description discloses the return structure (results array and meta fields), giving useful insight into output shape. However, it does not mention potential side effects, rate limits, authentication requirements, or pagination semantics beyond the presence of 'has_more', leaving some behavioral ambiguity.

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

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

The description is highly concise, consisting of two short sentences that front-load the core purpose and immediately describe the return format. No unnecessary words or repetition, making it easily scannable.

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 is simple with only two parameters, and the return format is described, which covers basic usage. However, it omits contextual details such as whether a site must be selected first (given the sibling discourse_select_site), how to handle pagination beyond 'has_more', and any error conditions, leaving some gaps for full contextual understanding.

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 description does not elaborate on the parameters, leaving max_results without explanation. The schema only describes 'query', providing 50% coverage, and the description adds no semantic value beyond what the schema already states, failing to clarify how max_results behaves.

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 'Search site content' and specifies the return format with 'matching topics' and metadata, indicating a search operation. However, it does not explicitly differentiate itself from sibling tools like discourse_filter_topics or discourse_get_query, so it lacks a bit of sibling distinction.

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 no guidance on when to use this tool versus alternatives. It does not mention any prerequisites (e.g., site selection) or scenarios where a different sibling tool would be more appropriate, such as filtering topics or running queries.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'validate' and returning JSON, but does not explain what validation entails (e.g., network request, error behavior), what 'select' means for subsequent tools, or any side effects. This is a significant gap for a tool that likely sets the working 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?

The description is extremely concise—two sentences that immediately communicate the core purpose and return format. Every word earns its place, and the front-loaded verb makes the tool's function instantly clear.

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 (one parameter, no output schema), the description is partially complete. It states the purpose and return format, but lacks details about validation behavior, error handling, or how this selection affects other tools. This leaves notable ambiguity for an AI agent using the tool for multi-step workflows.

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 already describes the only parameter ('site' as 'Base URL of the Discourse site') with 100% coverage. The description reinforces the site concept but adds no new parameter-level meaning beyond the schema, 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?

The description clearly states a specific action ('Validate and select') on a specific resource ('a Discourse site'), and distinguishes this tool from the sibling tools which all perform operations on an already-selected site. The return value ('JSON with site URL and title') further clarifies the tool's role.

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

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

Usage context is implied by the tool's name and sibling set (this must be called before other discourse_* tools), but the description does not explicitly state when to use it or mention alternatives. There is no direct guidance on prerequisites or sequencing, so it earns a mid-range score.

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