Server Quality Checklist

Tool Scores

• discourse_get_draftA
  4/5.0
  Behavior3/5

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

  Annotations already provide key behavioral hints (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true), covering safety and idempotency. The description adds minimal context beyond this, such as the examples of draft keys, but does not disclose additional traits like rate limits, auth needs, or what happens if the draft is missing. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is a single, efficient sentence that front-loads the purpose and includes helpful examples. Every part earns its place without redundancy, making it easy to scan and understand quickly.

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

  Completeness4/5

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

  Given the tool's low complexity (2 parameters, 1 required), rich annotations (covering safety and idempotency), and 100% schema coverage, the description is mostly complete. However, there is no output schema, and the description does not explain return values (e.g., draft content or error handling), leaving a minor gap in completeness.

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

  Parameters3/5

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

  Schema description coverage is 100%, with clear descriptions for both parameters (draft_key and sequence). The description adds value by providing common key examples (e.g., 'new_topic', 'topic_<id>'), which helps interpret the draft_key parameter, but does not add significant meaning beyond what the schema already documents. Baseline 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.

  Purpose5/5

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

  The description clearly states the verb 'retrieve' and the resource 'a specific draft by its key', with examples of common keys like 'new_topic' and 'topic_<id>'. This distinguishes it from sibling tools like 'discourse_list_drafts' (which lists drafts) by focusing on fetching a single draft via a key.

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

  Usage Guidelines4/5

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

  The description provides clear context by mentioning common key examples (e.g., 'new_topic' for new topic drafts, 'topic_<id>' for reply drafts), which helps guide when to use this tool. However, it does not explicitly state when not to use it or name alternatives, such as 'discourse_list_drafts' for listing all drafts.

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

• discourse_get_userA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds valuable context beyond annotations by specifying what information is returned (name, trust level, join date, bio, profile link) and clarifying the username format requirement ('without @ symbol'), which helps the agent understand the tool's behavior and output expectations.

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

  Conciseness5/5

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

  Two sentences with zero waste: the first states the purpose and mechanism, the second specifies the return values. Every element serves a purpose - no redundant information, no fluff, and the most important information (what the tool does) comes first.

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

  Completeness4/5

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

  For a simple read operation with comprehensive annotations (readOnlyHint, idempotentHint, destructiveHint) and 100% schema coverage, the description provides adequate context by specifying the return fields. However, without an output schema, the description could benefit from more detail about the response structure (e.g., whether fields might be null, format of dates). The description is mostly complete but has minor gaps in output specification.

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

  Parameters3/5

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

  Schema description coverage is 100% with the parameter fully documented in the schema ('The Discourse username to look up (without @ symbol, e.g., 'codinghorror')'). The description mentions 'by username' but adds no additional parameter semantics beyond what the schema already provides. With complete schema coverage, baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the specific action ('Get information about a Discourse user by username') and resource ('Discourse user'), distinguishing it from siblings like discourse_list_user_posts or discourse_list_user_chat_channels which list user content rather than retrieve user profile information. It specifies the exact lookup mechanism (by username) rather than a generic 'get user' operation.

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

  Usage Guidelines3/5

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

  The description implies usage context by specifying 'by username' and listing the returned fields, but doesn't explicitly state when to use this tool versus alternatives like discourse_search (which could find users) or discourse_list_user_posts (which focuses on content). There's no guidance on prerequisites or when-not-to-use scenarios.

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

• discourse_read_postA
  4/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, indicating a safe, repeatable read operation. The description adds value by specifying the return content (post content, author, creation date, link), which is useful context not covered by annotations, though it doesn't detail error handling or rate limits.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence and efficiently lists return values in the second. Both sentences earn their place by providing essential information without redundancy, making it appropriately sized and well-structured.

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

  Completeness4/5

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

  Given the tool's low complexity (single parameter, read-only operation) and rich annotations, the description is mostly complete. It specifies return values, which compensates for the lack of an output schema. However, it could improve by mentioning error cases or when to use versus siblings, but overall it's adequate for the context.

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

  Parameters3/5

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

  Schema description coverage is 100%, with the parameter 'post_id' fully documented in the schema. The description does not add any additional meaning beyond the schema, such as format examples or edge cases. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.

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

  Purpose5/5

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

  The description clearly states the specific action ('Read a specific post by its ID') and resource ('post'), distinguishing it from siblings like 'discourse_read_topic' (which reads topics) and 'discourse_list_user_posts' (which lists posts). It explicitly mentions the verb 'Read' and target 'post', avoiding tautology with the name/title.

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

  Usage Guidelines3/5

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

  The description implies usage when needing to read a specific post by ID, but does not explicitly state when to use this tool versus alternatives like 'discourse_read_topic' or 'discourse_list_user_posts'. No exclusions or prerequisites are mentioned, leaving usage context partially implied rather than clearly defined.

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

• discourse_list_categoriesA
  4.2/5.0
  Behavior3/5

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

  Annotations already cover key behavioral traits (readOnlyHint: true, destructiveHint: false, etc.), so the bar is lower. The description adds useful context about visibility ('visible to the current user') and return content ('category names and topic counts'), but does not disclose additional behaviors like rate limits or authentication needs beyond what annotations imply.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, followed by a brief utility note. Every sentence earns its place without redundancy, making it appropriately sized and efficient for an AI agent to parse quickly.

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

  Completeness4/5

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

  Given the tool's low complexity (0 parameters, no output schema) and rich annotations, the description is mostly complete. It covers purpose, usage context, and output details, but lacks information on potential limitations (e.g., pagination or sorting) that could be relevant for a list operation, preventing a perfect score.

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

  Parameters4/5

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

  With 0 parameters and 100% schema description coverage, the baseline is high. The description adds no parameter-specific information, which is fine since there are none. It effectively compensates by clarifying the output semantics, earning a score above the minimum viable.

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

  Purpose5/5

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

  The description clearly states the verb ('List') and resource ('categories visible to the current user'), specifying scope and distinguishing it from siblings like discourse_list_tags or discourse_list_user_posts. It explicitly mentions what is returned ('category names and topic counts'), making the purpose 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.

  Usage Guidelines4/5

  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 ('Useful for discovering where to post or search'), which helps guide usage. However, it does not explicitly state when not to use it or name alternatives (e.g., discourse_search for broader queries), so it falls short of a perfect score.

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

• discourse_list_chat_channelsA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond annotations: it specifies that channels are 'public' and 'visible to the current user', mentions support for 'filtering and pagination', and describes return content ('channel information including title, description, and member counts'), which is not covered by annotations. No contradiction with annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose and followed by key features (return content, filtering, pagination). Every sentence earns its place with no wasted words, making it efficient and easy to parse.

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

  Completeness4/5

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

  Given the tool's moderate complexity (list operation with filtering/pagination), rich annotations (covering read-only, non-destructive, open-world, idempotent), and 100% schema coverage, the description is mostly complete. It adds useful context like 'public' visibility and return content. However, without an output schema, it could benefit from more detail on response format (e.g., structure of returned channel objects), though the mention of 'channel information including title, description, and member counts' partially addresses this.

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

  Parameters3/5

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

  Schema description coverage is 100%, with all parameters well-documented in the schema (e.g., 'filter' for name/slug, 'limit' with defaults and max, 'offset' for pagination, 'status' for channel status). The description mentions 'Supports filtering and pagination' but does not add specific meaning beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the verb ('List') and resource ('all public chat channels visible to the current user'), specifying scope ('public', 'visible to current user') and distinguishing from siblings like 'discourse_list_user_chat_channels' which likely shows user-specific channels. It provides specific output details ('channel information including title, description, and member counts').

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

  Usage Guidelines4/5

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

  The description implies usage for retrieving public chat channels with filtering/pagination, but does not explicitly state when to use this tool versus alternatives like 'discourse_list_user_chat_channels' or 'discourse_filter_topics'. It provides clear context ('visible to the current user') but lacks explicit exclusions or named alternatives.

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

• discourse_list_user_postsA
  4.2/5.0
  Behavior4/5

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

  Annotations cover read-only, non-destructive, idempotent, and open-world hints, but the description adds valuable behavioral context: it specifies pagination details (30 posts per page, most recent first), return content (topic title, post date, excerpt, direct links), and clarifies the username format (without @ symbol). No contradictions with annotations; the description enhances understanding beyond 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.

  Conciseness5/5

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

  The description is front-loaded with the core purpose, followed by key behavioral details (pagination, content, ordering) in two efficient sentences. Every sentence adds value without redundancy, making it easy for an agent to parse and apply.

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

  Completeness4/5

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

  Given the tool's moderate complexity, rich annotations, and 100% schema coverage, the description is largely complete. It covers purpose, behavior, and output content, though no output schema exists. Minor gaps include lack of error handling or rate limit details, but overall it provides sufficient context for effective use.

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

  Parameters3/5

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

  Schema description coverage is 100%, with clear documentation for both parameters (username and page). The description adds minimal semantic value beyond the schema, such as implying pagination context and username format, but does not provide additional syntax or constraints. Baseline 3 is appropriate as the schema already handles parameter details effectively.

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

  Purpose5/5

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

  The description clearly states the specific action ('Get a paginated list of posts and replies by a specific user') and resource ('posts and replies'), distinguishing it from siblings like discourse_list_categories or discourse_search by focusing on user-specific content. It explicitly mentions the ordering ('most recent first') and content type, avoiding tautology with the name/title.

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

  Usage Guidelines4/5

  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: to retrieve posts and replies for a specific user with pagination. However, it does not explicitly state when not to use it or name alternatives (e.g., discourse_search for broader queries or discourse_read_post for single posts), though the sibling list implies differentiation. This is adequate but lacks explicit exclusions.

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

• discourse_read_topicA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond annotations by specifying that it 'Supports pagination for long topics,' which is a key behavioral trait not captured in annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose and followed by a key feature (pagination). Every sentence earns its place with no wasted words, making it highly efficient.

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

  Completeness4/5

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

  Given the tool's moderate complexity (3 parameters, no output schema) and rich annotations (covering safety and idempotency), the description is mostly complete. It adds useful context like pagination support but could benefit from mentioning response format or error handling, though not strictly required.

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

  Parameters3/5

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

  Schema description coverage is 100%, with each parameter well-documented in the schema (e.g., topic_id includes an example, post_limit specifies default and range). The description mentions pagination, which aligns with start_post_number but does not add significant meaning beyond what the schema provides.

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

  Purpose5/5

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

  The description clearly states the verb ('Read') and resource ('Discourse topic') with specific details about what is included ('metadata (title, category, tags) and posts'). It distinguishes from siblings like discourse_read_post (which reads a single post) and discourse_filter_topics (which lists topics).

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

  Usage Guidelines4/5

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

  The description implies usage for reading topics with pagination support, which differentiates it from list tools like discourse_list_categories. However, it does not explicitly state when to use this tool versus alternatives like discourse_search or discourse_read_post, nor does it provide exclusions.

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

• discourse_searchA
  4.2/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context about authentication requirements for private content ('requires authentication') and search operator capabilities, which goes beyond what annotations provide.

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

  Conciseness5/5

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

  Two sentences with zero waste. The first sentence establishes purpose and scope, the second provides practical usage guidance with examples. Every word earns its place, and information is front-loaded appropriately.

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

  Completeness4/5

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

  For a search tool with comprehensive annotations and full schema coverage, the description provides good context about search capabilities and authentication requirements. However, without an output schema, it doesn't describe the structure or format of search results, which would be helpful for an AI agent.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema fully documents all three parameters. The description mentions search operators like @username, #tag, category:name which aligns with the query parameter description but doesn't add significant semantic value beyond what's already in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the specific action ('Search') and resources ('Discourse site content including topics, posts, and users'), distinguishing it from siblings like discourse_filter_topics or discourse_list_tags which focus on specific content types. It provides a comprehensive scope that covers multiple content types in one search operation.

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

  Usage Guidelines4/5

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

  The description implicitly suggests using this tool for general content searches across multiple content types, but doesn't explicitly state when to use it versus alternatives like discourse_filter_topics or discourse_list_user_posts. It provides search operator examples but no explicit guidance on tool selection criteria.

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

• discourse_filter_topicsA
  4.3/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable context: 'Results are permission-aware' (access control behavior) and details on query syntax and pagination limits (e.g., 'max 50' in schema), which are not covered by annotations.

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

  Conciseness4/5

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

  The description is front-loaded with the core purpose and query language, followed by detailed syntax examples. It's efficient but slightly dense; every sentence adds value, though it could be more structured for readability.

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

  Completeness4/5

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

  Given the tool's complexity (rich query language, 3 parameters, no output schema), the description is mostly complete. It covers query syntax, permission-awareness, and pagination hints. However, it lacks explicit examples of return values or error handling, which would be helpful without an output schema.

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

  Parameters3/5

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

  Schema description coverage is 100%, with clear descriptions for 'filter', 'page', and 'per_page'. The description adds semantics by explaining the query language syntax (e.g., key:value tokens, operators for categories/tags) and numeric/free-text matching, but this mostly elaborates on what the schema implies for the 'filter' parameter.

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

  Purpose5/5

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

  The description clearly states the verb ('filter') and resource ('topics'), specifying it uses a 'concise query language' for filtering. It distinguishes from sibling tools like 'discourse_search' by focusing on structured query-based filtering rather than general search.

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

  Usage Guidelines5/5

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

  It explicitly states when to use this tool: for filtering topics with a structured query language. It distinguishes from alternatives by implying this is for permission-aware, structured filtering, unlike general search tools in the sibling list.

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

• discourse_get_chat_messagesA
  4.4/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable behavioral context by detailing the four query modes (pagination, date-based, message-based, last-read) and mentioning 'flexible pagination,' which helps the agent understand operational nuances beyond the basic annotations.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, followed by a bullet-like list of four supported scenarios in a single, efficient sentence. Every phrase adds value without redundancy, making it easy to parse while covering multiple use cases succinctly.

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

  Completeness4/5

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

  Given the tool's complexity (7 parameters, multiple query modes) and rich annotations, the description is mostly complete. It explains the key behavioral modes but lacks details on output format (e.g., structure of returned messages) since there's no output schema. However, it compensates well with clear usage scenarios and parameter context.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all parameters are documented in the schema. The description adds some context by grouping parameters into usage scenarios (e.g., target_message_id with direction for pagination, target_date for date-based queries), but it doesn't provide additional syntax or format details beyond what the schema already specifies. This meets the baseline for high schema coverage.

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

  Purpose5/5

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

  The description clearly states the specific action ('Get messages from a chat channel') and resource ('chat channel'), distinguishing it from sibling tools like discourse_list_chat_channels (which lists channels) or discourse_search (which searches content). It specifies the domain of chat messages rather than other Discourse entities.

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

  Usage Guidelines5/5

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

  The description explicitly outlines four distinct usage scenarios: (1) paginating with direction, (2) querying around a target_date, (3) getting messages around a target_message_id, and (4) fetching from last read position. This provides clear guidance on when to use this tool versus alternatives like discourse_search or discourse_list_user_posts for different data retrieval needs.

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

• discourse_list_draftsA
  4.4/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds value by specifying that it returns draft keys, sequences, and preview content, and that it's for the current user, which clarifies scope beyond the annotations. No contradictions with annotations are present.

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

  Conciseness5/5

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

  The description is two sentences that are front-loaded with the core purpose and followed by usage guidance. Every word contributes to clarity and utility, with no wasted information, making it highly efficient and well-structured.

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

  Completeness4/5

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

  Given the tool's low complexity (1 optional parameter), rich annotations covering safety and behavior, and no output schema, the description is mostly complete. It specifies the user scope and return data, but could slightly improve by mentioning pagination behavior (implied by 'offset') or error cases. However, it's sufficient for effective use.

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

  Parameters3/5

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

  Schema description coverage is 100%, with the single parameter 'offset' well-documented in the schema (pagination offset with default and range). The description does not add any parameter-specific information beyond what the schema provides, so it meets the baseline for high schema coverage without extra value.

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

  Purpose5/5

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

  The description clearly states the action ('List all drafts'), specifies the resource ('for the current user'), and distinguishes it from siblings by focusing on drafts rather than topics, posts, or other resources. It explicitly mentions the return data (draft keys, sequences, preview content), making the purpose specific and well-defined.

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

  Usage Guidelines5/5

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

  The description provides explicit usage guidance by stating 'Use this to find existing drafts before updating them,' which indicates when to use this tool (for listing drafts) and implies an alternative (updating drafts, likely via a sibling tool like discourse_get_draft). This helps the agent differentiate it from other list tools like discourse_list_user_posts.

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

• discourse_list_tagsA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate this is a read-only, non-destructive, idempotent, and open-world operation. The description adds useful context beyond annotations by specifying the return format ('tag names and usage counts') and the conditional availability ('if tagging is enabled'), enhancing the agent's understanding 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.

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, followed by additional context in a second sentence. Both sentences are essential—the first defines the tool, and the second provides usage guidance—with no wasted words or redundancy.

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

  Completeness4/5

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

  Given the tool's simplicity (0 parameters, no output schema) and rich annotations, the description is largely complete. It covers purpose, return values, and usage context. However, it could be slightly more comprehensive by explicitly mentioning the lack of filtering options or pagination details, though this is minor for a list tool.

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

  Parameters4/5

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

  The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the inputs. The description does not need to add parameter information, and it appropriately focuses on the tool's purpose and output, earning a baseline score of 4 for zero-parameter tools.

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

  Purpose5/5

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

  The description clearly states the verb ('List') and resource ('all available tags on the Discourse site'), specifying the scope ('if tagging is enabled') and what is returned ('tag names and usage counts'). It distinguishes from sibling tools like 'discourse_list_categories' by focusing specifically on tags.

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

  Usage Guidelines4/5

  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 ('if tagging is enabled') and hints at an alternative use case ('Use tags in search queries with #tagname'), but does not explicitly state when not to use it or name specific alternative tools for related functions.

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

• discourse_list_user_chat_channelsA
  4.4/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond annotations: it specifies the scope (user's channels, including public and direct messages) and mentions unread tracking information, which are behavioral details not covered by annotations.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that efficiently conveys the tool's purpose, scope, and key feature (unread tracking). Every word adds value without redundancy, making it front-loaded and easy to parse.

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

  Completeness4/5

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

  Given the tool's low complexity (0 parameters, no output schema) and rich annotations, the description is mostly complete. It covers purpose and behavioral context well, but could slightly improve by clarifying the output format or any limitations, though annotations help mitigate this gap.

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

  Parameters4/5

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

  There are 0 parameters, and schema description coverage is 100%. The description doesn't need to explain parameters, so it meets the baseline of 4 for having no parameters to document, which is appropriate given the empty input schema.

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

  Purpose5/5

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

  The description clearly states the verb 'List' and resource 'all chat channels for the currently authenticated user', specifying both public membership channels and direct message channels. It distinguishes from sibling tools like 'discourse_list_chat_channels' by focusing on the user's specific channels rather than all channels.

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

  Usage Guidelines4/5

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

  The description provides clear context: it lists channels for the 'currently authenticated user' and includes unread tracking. However, it doesn't explicitly state when to use this tool versus alternatives like 'discourse_list_chat_channels' or 'discourse_get_chat_messages', though the user-specific focus is implied.

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

• discourse_select_siteA
  4.4/5.0
  Behavior4/5

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

  Annotations cover key behavioral traits (read-only, open-world, idempotent, non-destructive), but the description adds valuable context beyond this: it specifies that the tool verifies site reachability and retrieves the site's title, which are not implied by annotations alone. No contradiction with annotations exists.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose and usage rule in two concise sentences, with no wasted words. Each sentence earns its place by providing essential information about functionality and context.

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

  Completeness4/5

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

  Given the tool's complexity (simple parameter, no output schema), the description is largely complete: it explains the purpose, usage context, and added behaviors like validation and title retrieval. However, it lacks details on error handling or what happens if validation fails, leaving a minor gap.

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

  Parameters3/5

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

  Schema description coverage is 100%, with the parameter 'site' fully documented in the schema. The description does not add any additional semantic details about the parameter beyond what the schema provides, such as format examples or validation rules, so it meets the baseline for high schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with specific verbs ('validate and select') and resource ('Discourse site'), explicitly distinguishing it from siblings by noting it must be called before other tools when multiple sites are configured. It goes beyond a tautology by explaining the validation and retrieval functions.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('Must be called before using other tools when multiple sites are configured'), which directly addresses its role relative to sibling tools. It clearly defines the prerequisite context without being misleading.

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

• search_discourse_communitiesA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable behavioral context by specifying the return format ('Returns communities with confidence scores and engagement metrics'), which helps the agent understand what to expect from the output despite no output schema being provided.

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

  Conciseness5/5

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

  The description is perfectly front-loaded with the core purpose, followed by clear usage rules and output information. Every sentence earns its place with zero wasted words, making it highly efficient for an AI agent to parse and understand.

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

  Completeness4/5

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

  Given the tool's moderate complexity (6 parameters, no output schema), the description provides excellent purpose clarity, usage guidelines, and behavioral context. While it doesn't explain all parameter interactions or edge cases, it gives the agent enough information to use the tool correctly, especially with the comprehensive schema descriptions available.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents all 6 parameters. The description adds minimal additional semantic context by briefly explaining the 'query' and 'similar_to' parameters, but doesn't provide meaningful information beyond what's already in the schema descriptions. This meets the baseline 3 for high schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with specific verbs ('Discover', 'find') and resources ('Discourse forum communities'), distinguishing it from siblings like 'discourse_search' (which appears to be a general search) by focusing specifically on community discovery through semantic search or similarity matching.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use each parameter ('Use 'query' for semantic text search... or 'similar_to' to find communities similar to a known one'), includes a clear exclusion rule ('Provide exactly one of 'query' or 'similar_to''), and distinguishes this community-focused search from other sibling tools that search different entities like topics or posts.

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