Server Quality Checklist

Tool Scores

• qq_sendA
  3.5/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Send') but does not disclose side effects, permissions, delivery guarantees, failure modes, or any state changes beyond the act of sending. The phrase 'whitelisted owner' hints at a prerequisite but is not elaborated, and no information about return values or errors is given.

  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 with no filler. It efficiently delivers the action, recipient, and parameter meaning, and even includes a clarifying parenthetical about the recipient. Every word contributes value.

  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?

  Given the tool has only 1 parameter, no output schema, and no annotations, the description is moderately complete. It defines the purpose and the parameter, and implies an active chat context. However, it lacks explicit information about expected behavior after sending, potential errors, or prerequisites beyond the implied 'whitelisted owner,' leaving some gaps for an agent to infer.

  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 does add meaning by explaining that 'message is the content,' which clarifies the single parameter's role. However, it does not provide details on format, length, or constraints, so compensation is minimal but present.

  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 ('Send') and the specific resource ('a private message to the current chat user'), with additional clarification that the recipient is 'the whitelisted owner from inbox.' This unambiguously distinguishes it from sibling tools like qq_poll_inbox (receive) and qq_status (status check).

  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 when to use the tool (when you want to send a private message) but does not explicitly state alternatives or when not to use it. There is no mention of sibling tools for receiving messages or other contexts where this would be inappropriate, so guidance is only implicit.

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

• qq_detachA
  3.8/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 that only the owner (matching tag) can release and that others get an error, which is valuable. However, it does not explain success behavior, whether the operation is idempotent, or any side effects (e.g., breaking the bridge connection).

  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 no wasted words. The action is front-loaded, and the usage guidance follows naturally. Every word earns its place.

  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 tool with a single parameter and no output schema, the description is reasonably complete but still lacks essential details: what happens on success, how the tag relates to ownership, and any impact on sibling tools (e.g., does releasing prevent sending?). More context would improve completeness.

  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%, and the description only mentions 'matching tag' without defining what the tag is, its format, or how to obtain it. The description does not adequately compensate for the missing schema detail.

  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 clear verb ('Releases') and resource ('QQ bridge'), and specifies an ownership constraint that distinguishes it from sibling tools like qq_attach. The purpose is unmistakable.

  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?

  Provides explicit usage context: 'Call when done or on new-conversation.' It also notes the owner-only condition. While it doesn't name alternative tools, the context is sufficient to guide when to use it.

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

• qq_statusA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry behavioral disclosure. It states 'Query' which implies a read-only operation, but it does not explicitly confirm no side effects or mention any conditions (e.g., authentication, connectivity). The listed fields give some insight into the response, but it does not disclose potential errors or limitations. Overall, it is minimally adequate but lacks explicit safety guarantees.

  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 with no wasted words. It efficiently communicates the action and the specific data points returned. It is concise and well-structured for immediate comprehension.

  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?

  Given the tool has no parameters and no output schema, the description fulfills all necessary context. It tells the agent exactly what the tool does and what fields will be in the response. There is no additional information an agent would need to correctly invoke this tool; it is complete for its simplicity.

  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, and the schema (empty object) already reflects this. Since there are no parameters to describe, the description is not required to add parameter details. The baseline of 4 is appropriate because the tool's interface is trivial and the description does not need to compensate for missing parameter docs.

  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 a specific verb ('Query') and resource ('bridge status'), followed by a concrete list of fields it covers (connection, bot QQ, private whitelist, group whitelist, inbox count). This unambiguously distinguishes it from sibling tools like qq_send or qq_poll_inbox, which are action-oriented.

  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?

  The description provides no guidance on when to use this tool versus alternatives. It does not mention typical scenarios (e.g., 'check before sending') or exclude cases where other tools are more appropriate. While the purpose is clear, the lack of usage context means an agent might not know when to invoke it without additional inference.

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

• qq_get_agent_profileA
  4.2/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses the file-read nature, the env-var path override (AGENTS_MD), and the intended system-prompt usage. However, it does not state what happens when the file is missing, whether results are cached across calls, or what the return value looks like — gaps that matter since there is no output schema to fill them.

  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?

  Three sentences, ~47 words, with clear front-loading: purpose first, then usage instruction, then configuration detail. No filler or repetition of schema facts, and every sentence 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 0-parameter, no-output-schema, no-annotation tool, the description covers the essential semantic ground: what it returns (the role profile), how to use it (load once as system prompt), and how to configure it (AGENTS_MD). The only omission is error-handling behavior, which is minor for a simple read 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 zero parameters, so the schema does no explanatory work; the baseline of 4 applies. The description adds useful config semantics by documenting that the path is overridable via the AGENTS_MD environment variable, which is the only 'input' mechanism an agent would need to understand.

  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 ('Get') with a defined resource ('AGENTS.md role profile') and spells out its content (personality, duties, security boundaries). It clearly distinguishes this from the other QQ bridge tools (qq_send, qq_poll_inbox, etc.) by framing it as an agent self-configuration read, not a chat or inbox 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 instruction 'Load it once and treat it as your system prompt while chatting through QQ' gives explicit, practical guidance on when and how to use it, which is distinctive enough among siblings. It lacks an explicit when-not-to-use clause or named alternatives, but the one-time init framing makes the usage context clear without needing to exclude the chat/inbox siblings.

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

• qq_poll_inboxA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It reveals the immediate-return vs. wait behavior, the timeout cap (max 30000 ms), a batch size limit (max 50), and an authorization constraint (whitelisted owner only). This is substantial, though it omits the return format and behavior on timeout.

  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 pack in the core action, access restriction, and behavioral details without fluff. The main purpose is front-loaded, and every clause delivers valuable information. This is a model of conciseness for a simple tool.

  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 tool with one optional parameter and no output schema, the description covers the essential context: what it fetches, who can use it, the timing model, and the limits. Minor gaps (return format, timeout behavior, non-owner handling) are acceptable given the tool's simplicity, but a bit more detail would make it 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 schema has a single parameter (timeoutMs) with 0% description coverage, so the description must compensate. It explicitly explains that timeoutMs controls the maximum wait time and caps at 30000, directly giving meaning to the parameter. It also adds a batch-size constraint that is not in the schema, enriching the tool's semantics.

  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 ('Fetch private messages received by the bot') and adds scope ('whitelisted owner only'). This clearly distinguishes it from siblings like qq_wait_inbox (which likely waits indefinitely) and qq_send (which sends messages). The polling behavior is also explicitly described, 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 in a polling context ('Returns immediately if new messages; else waits up to timeoutMs'), but it does not explicitly contrast with alternatives such as qq_wait_inbox or provide when-to-use/when-not-to-use guidance. The context is clear but exclusions are absent.

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

• qq_wait_inboxA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses the blocking behavior, the immediate return on message arrival, the timeout fallback, and the zero-polling benefit. It does not mention error conditions or return format, but for a wait primitive this is a strong disclosure.

  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?

  Three tightly written sentences, front-loaded with the core blocking behavior and efficient idioms. No wasted words – every sentence contributes meaning.

  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 wait tool with no output schema, the description covers the essential behavior and usage loop. It clarifies that it waits for 'new' messages and returns after the timeout. It doesn't elaborate on edge cases like pre-existing messages, but the context is sufficient for an agent to call it correctly.

  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 has 0% description coverage, so the description must compensate. It mentions 'or after maxWaitMs', which clarifies that the parameter is a timeout, but it does not specify units, default value when omitted, or range. The semantics are partially explained but lack detail.

  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 (BLOCK) and resource (inbox for private messages), and distinguishes itself from alternatives by emphasizing 'zero polling/cost while waiting' – an implicit contrast to qq_poll_inbox. The purpose is unmistakable.

  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?

  It provides explicit usage guidance ('Call in a loop to idle efficiently waiting for QQ messages') and explains the timeout behavior (returns after maxWaitMs). It does not name a specific alternative, but the 'zero polling' comment implies the context where this tool is preferred over polling, which is adequate.

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

• qq_attachA
  4.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 the full burden of behavioral disclosure. It does disclose the key mutation behaviors: the exclusivity semantics, the owner-tag mechanism, and the failure mode on conflict. It stops short of describing what happens on repeated calls or how the claim is released, but the core behavioral profile is transparent.

  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?

  Three tight sentences with zero filler. The most important constraint ('exclusive') is front-loaded, and the owner-tag purpose and failure behavior follow efficiently. Every sentence 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 one-parameter tool with no output schema, the description covers purpose, exclusivity, failure mode, usage timing, and parameter semantics. Minor gaps remain—release behavior and repeated-call semantics—but nothing an agent needs to invoke it correctly is missing.

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

  Parameters4/5

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

  Schema coverage is 0% (the schema only gives the tag's string type), so the description must compensate, and it does: it explains the tag identifies the owner, requires uniqueness, and gives a concrete example ('your session id'). This adds real semantic meaning beyond the bare 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?

  States a specific verb ('Claims'), a specific resource ('QQ bridge'), and a distinguishing scope qualifier ('for THIS conversation (exclusive)'). This makes the tool's exclusive-claim nature explicit and clearly differentiates it from siblings like qq_send and qq_poll_inbox, which serve entirely different functions.

  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?

  Provides clear when-to-use guidance ('Call once when you start handling QQ') and describes the conflict condition ('Fails if another conversation already claimed it'). However, it does not mention the complementary sibling qq_detach or explicitly state when not to call it, leaving some routing to inference.

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

• qq_take_disc_changeA
  4.5/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, and it does well: it discloses that the tool 'returns true once if a new-conversation signal is pending' and 'false otherwise,' and explains the meaning ('connector should start a fresh session'). It also implies a consumption behavior ('true once') without being overly verbose. It doesn't mention edge cases or side effects, but as a read-only check, this is sufficient.

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

  Conciseness5/5

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

  The description is two concise sentences, front-loaded with the core purpose and the return value context. Every word earns its place: it states the check, the return behavior, and the recommended usage timing without redundancy or filler.

  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 an extremely simple tool (no params, no output schema, no nested objects), the description is complete. It tells the agent what the tool does, what it returns, and when to call it. An agent can confidently invoke it without additional information. The meaning of 'true' is explicitly tied to starting a fresh session, closing the loop.

  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, and the schema is empty with 100% coverage. The baseline for zero parameters is 4, and the description adds no parameter information because none exists. No further explanation is needed.

  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: 'Check if the owner requested a DISC CHANGE (换碟) in private chat.' It uses a specific verb ('check') and resource (the DISC CHANGE request), and the behavior is unambiguously defined. It differentiates from sibling tools like qq_send or qq_poll_inbox, which serve entirely different functions, by focusing on a specific signal rather than messaging or inbox operations.

  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 on when to use it: 'Poll after handling inbox messages.' This tells the agent the timing relative to other operations. However, it doesn't explicitly mention when NOT to use it or name alternative tools, though the sibling set makes it obvious this is distinct from sending or waiting. The guidance is actionable 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.