Server Quality Checklist

Tool Scores

• random_quoteA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description must carry the burden. It discloses the key behavioral trait: randomness ('at random'). It also mentions that the verse comes from 'the annotated set,' implying a curated collection. While it does not explicitly state that the operation is read-only, the verb 'returns' and the nature of the tool make this obvious. It adds useful behavioral context beyond the 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 concise and front-loaded: two sentences that immediately state what the tool does and when to use it. There is no wasted text, 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?

  Given the tool's simplicity (one optional parameter) and no output schema, the description is largely complete. It explains the random selection and optional theme filter, and points to list_themes for theme enumeration. It does not describe the return format, but for a quote tool this is acceptable and not a significant 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 coverage is 100%, so the baseline is 3. The description says 'optionally restricted to a theme,' which essentially restates the schema property. It adds no new semantics about the parameter, such as behavior when omitted or the meaning of specific theme values. The schema itself already provides the enum and a description, so the description contributes little beyond redundancy.

  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 function: 'Returns one verse at random from the annotated set, optionally restricted to a theme.' This is a specific verb and resource, and the phrase 'For when you want a line rather than an answer to a specific situation' distinguishes it from sibling tools like find_quote, which target specific queries.

  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 explicit when-to-use guidance: 'For when you want a line rather than an answer to a specific situation.' This implies that find_quote is the alternative for specific questions, though it does not name it directly. It also mentions optional theme restriction and refers to list_themes, giving context on how to use the theme parameter.

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

• list_themesA
  4.3/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 output format (one-line gloss and verse counts) and implies a read-only operation via 'lists'. However, it doesn't explicitly state safety, auth requirements, or any edge-case behavior, so it's not fully 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?

  The description is two sentences, front-loaded with the main action, and every word adds value. It avoids repetition and is well-structured.

  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, no output schema, and no annotations, the description provides sufficient context: what it returns, how it's structured, and why to use it. It is complete for its complexity.

  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 there are no parameter semantics to explain. The description doesn't need to add parameter context, hence baseline 4 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 uses a specific verb 'Lists' and resource 'theme vocabulary used to tag the corpus', clearly distinguishing it from sibling tools that return quotes, not themes. It also specifies the output includes glosses and verse 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?

  It explicitly mentions the tool is useful for browsing or for picking a theme argument for find_quote, giving clear context on when to use it. However, it doesn't explicitly exclude other scenarios or name alternatives with usage comparisons.

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

• quote_cardA
  4.4/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full behavioral disclosure. It clearly states the output is a PNG file, it is written to a temp file, copied to the macOS clipboard, and returns only the file path as text (never the image itself). This gives the agent a complete picture of side effects and return behavior.

  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 three sentences long and packs in the core purpose, the parameter relationship, and the return behavior. It is front-loaded and every sentence contributes, though slightly more verbose than strictly necessary.

  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 4 optional parameters, no output schema, and no annotations, the description is highly complete. It explains what the tool returns (file path text), the macOS clipboard side effect, and how the mode selection works, so an agent can invoke it confidently without additional documentation.

  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 baseline is 3. The description adds minimal new meaning beyond the schema; it reiterates the situation/verse relationship already in the schema. It does add some context about caption formatting (italic, one line, shrunk/clipped) but this is marginal.

  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 the tool renders one verse as a PNG quote card, writes it to a temp file, and puts it on the clipboard. This is a specific verb+resource (render verse) that clearly distinguishes it from siblings like find_quote, random_quote, and list_themes.

  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 explains two usage modes (situation or verse) and the intended use case (pasting into Slack or a doc). It does not explicitly name alternatives or when not to use, but the context is clear enough for an agent to select this over siblings.

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

• find_quoteA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description must carry the behavioral disclosure itself. It states that results are verses with chapter citation, ordered best match first, and gives input-pattern examples. It doesn't address no-match behavior or side effects, but the disclosed behavior and return ordering provide solid transparency for a simple search 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?

  Three sentences carry purpose, usage examples, output format, and an alternative-tool pointer without repetition. The examples are substantive rather than padding, and the most important verb/resource phrase is front-loaded.

  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 no annotations or output schema, the description covers the essential user journey: what it returns, how to phrase input, and where to go for an alternative workflow. It wisely leaves parameter detail to the schema; the only omission is explicit error/no-result handling, but that is not core to selecting the 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 input schema already fully documents all three parameters (count, theme, situation) at 100% coverage, so the baseline is 3. The description adds value by instructing users to describe the situation 'in plain words, including how it feels' and offering concrete example phrases, which clarifies the intended input format beyond the schema's generic 'plain language' note.

  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 is specific: 'Finds the Art of War verses that fit a described situation,' naming both the resource (Art of War verses) and the action (semantic matching). It explicitly distinguishes from the list_themes sibling with the caveat about browsing vocabulary, and the 'fit a described situation' phrasing clearly separates it from random_quote.

  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 gives concrete when-to-use guidance through examples of situations ('PM keeps adding scope...') and advises using list_themes first if the user wants to browse vocabulary instead of describing a situation. This is an explicit alternative, satisfying the when/when-not requirement even though random_quote and quote_card are not named.

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