Server Quality Checklist

Tool Scores

• discourse_get_userB
  3.4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds useful context about the returned fields, especially staff flags, but does not disclose edge cases such as behavior for nonexistent usernames, authentication needs, or response shape. 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 compact sentence with no filler. It front-loads the core purpose ('public profile') and efficiently enumerates the key fields, making it easy for an 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?

  For a simple one-parameter read-only lookup with no output schema, listing the main response fields is largely sufficient. The description is slightly thin on error behavior or the full set of returned fields, but these are minor for this tool's simplicity.

  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 'username' already documented including the 'no leading @' note. The tool description adds no parameter-level semantics beyond what the schema provides, 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.

  Purpose4/5

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

  The description identifies the resource ('a user's public profile') and the specific fields returned (name, trust level, bio, staff flags). It is clear and distinct from sibling tools that operate on topics, posts, or messages, though it lacks an explicit verb and does not name a sibling alternative.

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

  Usage Guidelines2/5

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

  No guidance is given about when to use this tool versus alternatives, nor any exclusions or prerequisites. The intended use is only implied by the phrase 'public profile'; there is no explicit mention of when another tool might be more appropriate.

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

• discourse_list_private_messagesA
  3.6/5.0
  Behavior3/5

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

  The annotations already declare readOnlyHint and openWorldHint, and the description is consistent with them. The description adds useful context about bot-owned topics and mailbox scoping, but it does not discuss ordering, pagination behavior, or the meaning of mailboxes like 'new' and 'unread'.

  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?

  A single sentence with no filler. The verb, resource, and scope are front-loaded, making it easy to scan.

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

  Completeness3/5

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

  For a simple all-optional-parameter read-only list operation, the definition is minimally viable: it states what is listed and the mailbox scope. However, with no output schema and no guidance on page/per_page semantics, some ambiguity remains for an agent deciding how to paginate or interpret results.

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

  Parameters2/5

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

  Schema description coverage is only 33%: only 'mailbox' has documentation ('default inbox'), while 'page' and 'per_page' have no descriptions. The description mentions 'mailbox' but does not compensate for the unexplained pagination parameters.

  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 uses a specific verb ('List') and identifies the exact resource: the bot's private-message topics, scoped by mailbox. This clearly distinguishes it from discourse_read_private_message (which reads one message) and discourse_search, even without naming those siblings.

  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 intended use is implied by 'bot's private-message topics in a mailbox,' but there are no explicit when-to-use or when-not-to-use conditions. An agent is not told to prefer discourse_read_private_message for individual message content or discourse_search for broader queries.

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

• discourse_list_notificationsA
  3.8/5.0
  Behavior4/5

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

  Annotations already include readOnlyHint=true, and the description adds meaningful behavioral detail by explicitly guaranteeing it 'does not clear unread.' This addresses a common side-effect expectation for notification endpoints and clarifies the bot-specific scope beyond the annotation.

  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 short sentences front-load the resource scope, then add the key behavioral caveat. There is no filler, redundancy, or unnecessary detail.

  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 list tool with two optional, well-described parameters and readOnly annotations, the description sufficiently covers scope and side effects. It doesn't describe result fields, but no output schema exists and the enumerated notification types give a reasonable sense of the content.

  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 `limit` and `filter` fully described. The description provides no additional parameter-level meaning, 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.

  Purpose4/5

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

  The description uses a specific verb and resource: 'The bot's OWN notifications (mentions, replies, likes, PMs)' — clearly indicating this lists notifications rather than messages or topics. It distinguishes from siblings by emphasizing the bot's own scope, though it doesn't explicitly name or contrast alternatives.

  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 as a safe, read-only peek and states it 'does not clear unread,' which gives useful context. However, it provides no explicit guidance on when to choose this tool over sibling tools like discourse_list_private_messages or discourse_search, nor any exclusion criteria.

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

• discourse_searchA
  3.8/5.0
  Behavior3/5

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

  Annotations already indicate readOnlyHint and openWorldHint, so the description does not need to cover safety. It adds that search is full-text and returns topics rather than posts, but does not disclose ordering, pagination behavior, or any limitations beyond the schema, so the added behavioral context is limited.

  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 sentence with no filler, front-loading the action and immediately clarifying the result shape. Every word earns its place, making it easy for an 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?

  The tool is simple with three well-documented parameters and safety annotations, so the description does not need to over-explain. It covers the essential purpose and return fields, which is especially valuable given the absence of an output schema. Minor gaps such as explicit result ordering or pagination notes are not critical because the schema fills in parameter behavior.

  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 three parameters are already documented with meaningful details such as 'Discourse search syntax supported' and 'max topics to return'. The description adds no parameter-specific meaning beyond what the schema provides, 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.

  Purpose5/5

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

  The description states a specific verb and resource: 'Full-text search of the forum', and clearly defines the output as matching topics with id, slug, and title. This distinguishes it from sibling read/list tools, which focus on specific resources or listings rather than search.

  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 the tool is for searching the entire forum for topics, giving it a clear use case. However, it does not explicitly mention when not to use it or contrast it with alternatives like discourse_read_topic or discourse_list_categories, leaving sibling differentiation to inference.

  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/5.0
  Behavior4/5

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

  The description adds meaningful behavioral details beyond the readOnlyHint annotation: posts are returned as raw markdown, ordered oldest first, and start_post_number is optional. This helps the agent understand the expected output format and ordering without needing to invoke the tool. It does not describe pagination or error behavior, but the annotations already establish safety.

  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?

  A single sentence conveys the essential action, resource, format, ordering, and optionality with zero filler. The most important information is front-loaded and every clause earns its place.

  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 tool with all parameters documented and readOnlyHint/openWorldHint annotations, the description covers the core behavior: what is read, the format, and ordering. There is no output schema, so an ideal description might mention that multiple posts are returned, but 'a topic's posts' already implies this. Minor gaps around response shape are acceptable given the low complexity.

  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 input schema fully documents all three parameters. The description adds only a minor clarification about 'optional start', which aligns with start_post_number but does not materially expand on the schema. The baseline of 3 is appropriate because the schema carries the semantic weight.

  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 uses a specific verb and resource: 'Read a topic's posts', which clearly distinguishes it from sibling tools like discourse_read_post (single post) and discourse_search. It also specifies the output format (raw markdown) and ordering (oldest first), leaving no ambiguity about what the tool does.

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

  Usage Guidelines3/5

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

  The description implies usage for reading posts within a topic, and the optional start clause suggests parameter flexibility, but it gives no explicit guidance on when to choose this tool over discourse_read_post or discourse_search. No exclusions or alternative conditions are stated, so the agent must infer the appropriate context from the tool name and siblings.

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

• discourse_read_private_messageA
  4.2/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, so the read-only nature is covered. The description adds value by disclosing the raw post format and, more importantly, the error behavior when the topic is not a PM—information not present in the annotations or schema.

  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, front-loaded sentence that immediately states the action and resource, then adds the critical error condition. Every word earns its place, and there is no redundant filler.

  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 tool with three well-documented parameters and a readOnlyHint annotation, the description covers the key behavioral context: what is read, in what form, and when it fails. There is no output schema, but 'posts (raw)' gives a reasonable expectation of the return content, and the pagination-related parameters are already documented in the 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 each parameter already explained (topic_id, post_limit, start_post_number). The description does not need to add parameter-level detail; it complements the schema by tying topic_id to the PM-topic concept, but adds no meaning beyond what the schema already 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 states a specific verb ('Read') and a specific resource ('a private-message topic's posts (raw)'), which clearly differentiates this from reading a regular topic or a single post. It also adds a precise error condition ('Errors if the topic is not a PM'), 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.

  Usage Guidelines4/5

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

  The description gives clear context for when to use the tool: reading the posts of a private-message topic. The explicit error condition 'Errors if the topic is not a PM' acts as an exclusion, signaling the agent not to use this tool for non-PM topics, though it does not name the alternative like discourse_read_topic.

  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.3/5.0
  Behavior3/5

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

  The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the output fields but discloses no additional behavior such as pagination, ordering, or visibility filters; with annotations covering the safety profile, this is adequate but not rich.

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

  Conciseness5/5

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

  A single front-loaded sentence that names the action, resource, and key return fields with no filler. Every word contributes to understanding.

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

  Completeness5/5

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

  For a simple no-parameter read-only tool, the description is complete: it states what is listed and what fields are returned. With annotations confirming safety and no output schema, nothing essential is missing.

  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 zero parameters, so the schema already fully covers parameter semantics. The description does not need to explain inputs, and per the baseline for zero-parameter tools, this is appropriately handled.

  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 states a specific verb ('List'), a clear resource ('the forum's categories'), and the returned fields (id, name, slug, topic count). This distinguishes it from sibling tools that operate on topics, posts, users, notifications, and private messages.

  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 clearly communicates the purpose: retrieve the forum's categories with basic metadata. There are no sibling tools that list categories, so no explicit alternative or exclusion is necessary; the context is unambiguous.

  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.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the agent knows this is a safe read. The description adds useful behavioral context by specifying that the result includes raw markdown and metadata, going beyond a generic 'read post' statement. No contradictory behavior is described.

  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 sentence with no filler. It front-loads the action and resource, then specifies the input and output. Every word contributes to understanding the tool's purpose.

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

  Completeness5/5

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

  For a one-parameter read-only tool with no output schema, the description is sufficient: it names the input, the scope, and the return content. The annotations cover the safety profile, and the simplicity of the tool means no additional explanation is necessary.

  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?

  The schema already describes post_id as 'the post id' with 100% coverage, so the description's 'by post id' adds no additional semantic detail. This is an adequate baseline for a fully schema-documented single 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 a specific verb ('Read'), a specific resource ('a single post'), the input key ('by post id'), and the output type ('raw markdown and metadata'). This distinguishes it from sibling tools like discourse_read_topic or discourse_search by focusing on a single post and its raw content.

  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 phrase 'by post id' gives clear context for when to use this tool: when the agent already has a post_id and needs that specific post's content. It does not explicitly name alternatives or exclusions, but the intended use case is unambiguous given the sibling tool names.

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