Server Quality Checklist

Tool Scores

• xmpp_statusA
  3.6/5.0
  Behavior2/5

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

  No annotations are provided, and the description does not disclose any behavioral details such as authentication requirements, side effects, or what 'restricted' entails. It simply states the action without additional context.

  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, concise sentence with no unnecessary words. It is 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?

  The output schema is present, so return values are covered elsewhere. The description adequately states the tool's purpose for a zero-parameter status check, though it could elaborate on the meaning of 'restricted' to be fully complete.

  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 description does not need to explain parameter semantics. The baseline of 4 applies because the schema is empty and there is nothing to document.

  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 'check' and identifies two resources: the restricted XMPP connection and the durable message cursor. This clearly distinguishes from sibling tools that send messages, set state, poll, or wait.

  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 explicit guidance is provided on when to use this tool versus alternatives. The description does not mention sibling tools or suggest usage scenarios, leaving the agent to infer from the name and context.

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

• xmpp_poll_messagesA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full responsibility for disclosing behavior. It explicitly states 'Read' (non-destructive) and 'without blocking' (non-blocking execution), and hints at cursor persistence ('durable cursor'). This covers the essential safety and execution profile, though deeper details (e.g., whether the cursor auto-advances, error conditions) are not disclosed.

  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. Every word earns its place: 'Read' (verb), 'allowlisted messages' (object), 'after a durable cursor' (mechanism), and 'without blocking' (behavior). There is zero fluff or redundancy, making it an excellent model of concise writing.

  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?

  The output schema exists, so return values are not the description's responsibility. However, given the moderate complexity of a cursor-based polling tool, the description misses key context: what 'allowlisted' means, how the cursor should be managed, and what `request_id` is for. These gaps make it minimally viable but not fully complete.

  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 0%, so the description must compensate for parameter meaning. It effectively explains `after_cursor` via 'after a durable cursor' but provides no insight into `limit` or `request_id`. `request_id` in particular is cryptic and remains unexplained, leaving two of three parameters semantically underdefined.

  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 ('Read'), identifies the resource ('allowlisted messages'), and adds crucial modifiers ('after a durable cursor', 'without blocking') that clearly distinguish it from sibling tools like `xmpp_wait_for_message` (blocking) and `xmpp_send_message` (sending). This precisely conveys the tool's function and scope.

  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 'without blocking' provides clear context that this tool is intended for non-blocking message retrieval, implicitly contrasting with `xmpp_wait_for_message`. It does not explicitly name alternatives or define exclusion criteria, but the context is strong enough that an agent would know when to choose this over a blocking wait.

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

• xmpp_wait_for_messageA
  4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It adds meaningful behavioral context by disclosing that timeout_seconds is clamped to 1..1800 seconds and that a timeout is a normal result, which prepares the agent for possible empty or null returns. It does not cover all behaviors (e.g., whether it consumes the message), but it provides substantial useful detail.

  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 primary purpose in the first sentence, followed by a single second sentence that adds a critical behavioral note. It is concise with no redundant words or restatement of schema fields, earning top marks.

  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 and the presence of an output schema, the description adequately covers the essential behavior (blocking wait, timeout clamping, normal timeout). It leaves some domain context implicit (e.g., what 'allowlisted' means, how to get a cursor), but this is acceptable given sibling tools and schema. Minor gaps prevent a perfect score.

  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 0%, so the description must compensate. It clarifies 'after_cursor' by referencing 'after a durable cursor' and explains the clamping behavior of 'timeout_seconds'. However, it does not describe 'request_id' at all, and the schema only provides names/types without descriptions. The partial coverage is helpful but not complete.

  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 ('Wait for') and a precise resource ('next allowlisted message'), along with a positional constraint ('after a durable cursor'). This clearly distinguishes it from the sibling polling tool 'xmpp_poll_messages' by implying a blocking wait rather than a poll.

  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 blocking waits (as opposed to polling) and notes that a timeout is a normal outcome, but it does not explicitly compare with alternatives like xmpp_poll_messages or state prerequisites (e.g., how to obtain a durable cursor). Guidance is implied rather than explicit.

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

• xmpp_set_chat_stateA
  4.3/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses important constraints (allowlisted JID, fixed recipient, request_id condition) but omits operational details such as error handling, idempotency, or connection requirements. The term 'Publish' implies a side effect, but the description does not elaborate on what the agent should expect.

  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 three concise sentences with the purpose front-loaded. Every sentence adds value: purpose, allowed state values, and request_id guidance. There is no wasted text.

  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 2-parameter tool with an output schema, the description covers purpose, constraints, and parameter semantics. It lacks a few edge-case details (e.g., error behavior, exact output), but the output schema likely fills that gap. The description is sufficient for an agent to select and invoke the tool correctly in most cases.

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

  Parameters5/5

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

  Schema description coverage is 0%, and the schema has no enums or descriptions. The description compensates fully by enumerating valid state values ('active, composing, paused, inactive, or gone') and explaining when to pass request_id ('when the peer preserves XMPP threads'). This adds essential meaning beyond the raw 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 action: 'Publish an XEP-0085 chat state to the single allowlisted JID.' This is a specific verb and resource, and it distinguishes the tool from sibling tools like xmpp_send_message and xmpp_poll_messages by focusing on chat state publication.

  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: the recipient is allowlisted and cannot be overridden, and request_id should be passed when the peer preserves XMPP threads. However, it does not explicitly state when to use this tool versus alternatives, or provide exclusions, so it stops short of a 5.

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

• xmpp_send_messageA
  4.4/5.0
  Behavior4/5

  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 reveals a key restriction (recipient cannot be overridden) and explains the request_id correlation mechanism, adding context beyond the schema. However, it does not mention side effects, error behavior, or delivery semantics.

  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 primary action, and immediately provides a necessary constraint and a valuable usage tip. Every word earns its place without redundancy or fluff.

  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 send operation with an output schema, the description covers the core action, the fixed recipient restriction, and request_id usage. It lacks authentication or error-handling context, but the output schema likely documents return values, and sibling tools provide workflow context.

  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?

  Schema description coverage is 0%, but the description compensates by clarifying the text parameter as the message content through 'Send text' and explaining request_id's purpose for response correlation. It does not specify formatting constraints for text, but the meaning is strongly implied.

  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 explicitly states 'Send text to the single configured allowlisted JID,' providing a clear verb, object, and target. It distinguishes itself from sibling tools (polling, status, chat state) by focusing on the sending action and highlights the fixed recipient constraint.

  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 implies the tool is for sending outgoing messages, which is distinct from the sibling polling and waiting tools, but it does not explicitly state when to use it over alternatives. It provides specific guidance for request_id ('Reuse request_id to correlate a response'), though it lacks when-not-to-use exclusions.

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