Server Quality Checklist

Tool Scores

• complete_itemA
  3.9/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 of behavioral disclosure. It discloses the key state-changing effect (moving to recently-bought section), but does not mention reversibility, required permissions, or any side effects. The core effect is present, but additional behavioral context would be helpful for a mutation tool.

  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 compact and front-loaded with the tool's purpose before the parameter details. Every sentence adds distinct value, and there is no filler or redundant content.

  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 description, combined with the output schema and sibling context, is sufficient for a simple three-parameter mutation tool. It covers what the tool does, the main effect, and all parameter meanings. It slightly lacks explicit caveats about edge cases such as missing items or duplicate names without a uuid, but overall it is complete enough for correct invocation.

  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%, but the description fully documents all three parameters with practical guidance: item gets an example, list explains name-or-uuid and default behavior, and item_uuid explains its source and purpose. This fully compensates for the schema's lack of descriptive text.

  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 clearly states a specific action — ticking an item off as purchased — and the effect of moving it to the recently-bought section. This differentiates it from sibling operations like add_item and remove_item, though it could more explicitly say 'mark as completed'.

  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 gives implied usage context by explaining how to disambiguate duplicate item names with item_uuid from get_list_items, and how to omit list to use the default. However, it does not explicitly state when to use this tool instead of remove_item or add_item, leaving the comparison to inference.

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

• get_list_itemsA
  4.3/5.0
  Behavior4/5

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

  It discloses that the result includes both items still to buy and recently purchased ones, and that each item carries a uuid usable by sibling mutation tools. Since no annotations are provided, this behavioral context is valuable. It stops short of explicitly confirming the operation is read-only or mentioning permission requirements, but the 'Get' framing and return-focused wording cover the essential behavior.

  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 compact and front-loaded with the core purpose, then organized with an Args section. Every sentence adds meaningful information: the return scope, the list parameter behavior, and the uuid handoff. There is no filler or repetition of the schema.

  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 read-style tool with one optional parameter and an output schema, the description covers the essential call contract: parameter format, default behavior, return scope, and uuid semantics. It leaves out minor edge cases such as list-not-found errors, but the output schema covers return structure. It is sufficiently complete for reliable invocation.

  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?

  The schema provides only the parameter title 'List' with a default of null and no description. The description fully compensates by explaining that the list parameter can be a name or uuid and that omitting it uses the BRING_LIST default. This gives the agent everything it needs to correctly set the 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 states a specific verb and resource: 'Get the items on a shopping list.' This distinguishes it from siblings like get_lists, which retrieves lists, and add_item/remove_item/complete_item, which mutate items. The tool's role as a retrieval operation for list items 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 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 reading items and then passing their uuid to remove_item or complete_item, and it notes that the list argument can be omitted for a default. However, it does not explicitly state when to prefer this tool over get_lists or the mutation tools, nor does it give exclusion conditions. Usage context is implied rather than fully spelled out.

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

• get_listsA
  4.3/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 transparently discloses that the tool returns all lists on the account (scope) and the specific return fields (uuid and name), which is sufficient behavioral context for a read-only listing operation. It does not overstate side effects, and no contradictions exist.

  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. Every phrase ('every', 'on the account', 'with its uuid and name') adds specification and earns its place.

  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 zero-parameter operation with an output schema present, this description provides the essential information: the action, the resource scope, and the returned fields. It lacks nothing needed for correct invocation.

  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 input schema already covers 100% of parameters (zero parameters), so there is nothing to add from the description. The description focuses on output fields rather than inputs, which is appropriate. Baseline 4 for a zero-parameter tool.

  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 precise resource ('every Bring! shopping list on the account'), and the included fields ('uuid and name'). This clearly distinguishes it from item-focused siblings like get_list_items, add_item, remove_item, and complete_item.

  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 retrieving the full set of shopping lists at the account level, but it does not explicitly state when to use this tool instead of the item-focused siblings. There is no exclusion or alternative guidance, so the agent must infer usage from tool names.

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

• add_itemA
  4.6/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 explicitly states that the tool either adds an item or updates the note on an existing one, making the mutating nature clear. It does not detail edge cases like whether the note is replaced or merged, but the core side effect is transparently 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 compact and front-loaded: a one-sentence purpose followed by a concise, well-formatted Args block. Every sentence adds value, and there is no redundant or filler text.

  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 three-parameter tool with an existing output schema, the description covers everything needed to invoke it correctly: the operation, the add/update nuance, and all parameter semantics including the default list behavior. No critical information is missing.

  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%, so the description fully compensates. It explains each parameter with concrete examples ('Milk', '2 litres'), clarifies specification is an optional note, and defines the list parameter as 'List name or uuid. Omit to use the BRING_LIST default.' This adds significant 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?

  The description opens with a specific verb+resource statement: 'Add an item to a shopping list, or update the note on an existing one.' This clearly distinguishes the tool from its siblings (remove_item, complete_item, get_lists, get_list_items) by naming the exact operation and the add-vs-update behavioral split.

  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: use this tool to add an item or update an existing item's note. It does not explicitly exclude or route to sibling tools like remove_item or complete_item, but the purpose is so specific that an agent can reliably infer when this tool applies.

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

• remove_itemA
  4.6/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 explicitly states the destructive nature of the operation and clarifies two non-obvious behaviors: the BRING_LIST default when list is omitted, and oldest-match removal when item_uuid is not given. It does not document failure modes or idempotency, but the essential behavioral traits are clearly 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 compact and front-loaded: one purpose sentence followed by a concise three-line Args block with no filler. Every sentence earns its place by contributing information needed to call the tool correctly.

  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?

  The definition is complete for an agent to invoke correctly: all parameters are explained, the default-list behavior and duplicate-handling policy are stated, and an output schema exists so return-value documentation is unnecessary. The sibling tool names cover the remaining edge case of marking an item as purchased.

  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%, but the Args section fully compensates by explaining each parameter with examples and relationships (e.g., item_uuid sourced from get_list_items, and the behavior when it is omitted). This adds significant meaning beyond the bare schema titles.

  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 opening sentence gives a specific verb and resource ('Delete an item from a shopping list') and adds the crucial distinction 'without marking it as purchased', which clearly differentiates it from the sibling complete_item. This is unambiguous and 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 Guidelines4/5

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

  The description implies when to use this tool by contrasting deletion with marking purchased, but it does not explicitly name complete_item as the alternative. It does provide clear guidance on optional parameters (omit list to use the BRING_LIST default, supply item_uuid to disambiguate duplicates), helping an agent decide how to invoke it correctly.

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