Server Quality Checklist

Tool Scores

• cache_statsA
  3.7/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It adds a genuinely useful behavioral nuance: tokensServed equals tokens saved only for entries avoiding regeneration, not for cached file reads. It does not explicitly state read-only behavior, but 'analytics' and the absence of mutation verbs imply no side effects.

  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 tight sentences with the label front-loaded in 'Cache analytics'. The first sentence enumerates the return metrics; the second adds a necessary caveat about tokensServed. No 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 zero-parameter analytics tool with no annotations or output schema, the description covers the main return values and even clarifies a subtle metric. It does not specify the exact response container or explicitly state that the call is read-only, but those are minor gaps for this simple 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 parameter documentation is moot. The rubric's baseline for 0 params is 4, and the description needs no clarifification of parameter semantics.

  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 tool as 'Cache analytics' and lists concrete metrics (entry/edge counts, exact-match hit rate, queryHits/queryMisses, tokensServed), making its role clear. It is distinguishable from the sibling get/set/query/related/invalidate tools by being an analytics/stats tool, though it lacks an explicit verb like 'retrieves'.

  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 does not mention siblings or exclusions, but the phrase 'Cache analytics' plus the metric list implies this is the tool to use when cache statistics are needed. There is no explicit when-not-to-use guidance, so it stops short of a 4.

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

• cache_queryA
  3.8/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the full burden of behavioral disclosure. It adds useful context: the search spans all cached entries and matches by meaning rather than exact key, implying a read-only lookup. However, it does not state whether it mutates anything, what it returns, or any performance implications of scanning all entries.

  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?

  Two sentences, front-loaded with the core function and then the trigger condition. The 'knowledge-graph equivalent' metaphor adds color but somewhat restates the first sentence, making it slightly less tight than it could be. Overall, it is still concise and well-structured.

  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 description covers what the tool does and when to use it, and the schema covers parameters. However, since there is no output schema, the description omits any indication of return shape or size. It also doesn't mention potential cost or side effects of searching 'all cached entries,' so the profile is adequate but has clear gaps.

  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 documented meaningfully (text, top_k, min_similarity). The tool description adds no parameter-specific information beyond what the schema provides, so the baseline 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: 'Semantic search across all cached entries.' It also draws a clear contrast with 'exact key matching,' which distinguishes it from sibling tools like cache_get. An agent can tell what this tool does without opening the schema.

  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 says when to use the tool: 'when you suspect something related was already computed even though the prompt wording differs.' It implies exact-key lookups are not its purpose by stressing 'independent of exact key matching,' though it doesn't name a specific alternative tool.

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

• cache_invalidateA
  3.9/5.0
  Behavior4/5

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

  With no annotations provided at all, the description carries the full burden of behavioral disclosure. It does well: it reveals the destructive nature ('Delete'), the cascade semantics ('every entry that declared this one as a derived_from parent'), and recursion behavior. It does not mention edge cases like missing-id handling or irreversibility, but the core behaviors are transparent.

  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?

  Two sentences with no filler; the core action is front-loaded and the cascade nuance follows. The second sentence is semantically dense with nested clauses but earns its length by explaining recursive behavior and the rationale. Slightly compressed structure, but every part adds value.

  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 destructive 2-parameter tool with no annotations and no output schema, the description covers the main essentials: purpose, trigger scenario, and the cascade option's full behavior. Missing details are limited to edge-case behavior (nonexistent id, error handling, reversibility), which are conventional for cache invalidation and not severe gaps for an agent to proceed.

  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 only 50%: the cascade parameter has a schema description but id does not. The description enriches the cascade semantics well (derived_from parent, recursive invalidation), adding meaning beyond the schema's 'Also delete entries derived from this one'. However, id receives no additional semantic context, and the description doesn't fully compensate for the missing id doc, though the parameter is fairly self-explanatory.

  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 the action ('Delete a cache entry') and the specific resource, with a concrete motivating example ('underlying source it was based on changed'). It is clearly distinct from sibling cache_get/cache_set operations by virtue of being a deletion, though it does not explicitly name and differentiate from sibling tools.

  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 a clear when-to-use scenario: invalidate when the underlying source changed. It also explains the key decision between cascading and non-cascading deletion ('dependency-graph invalidation instead of a manual hunt for stale copies'). It lacks explicit exclusions or named alternatives, but the context is sufficiently clear.

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

• cache_relatedA
  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 behavioral burden and does well: it explains that traversal is outward, that edges are auto-linked by similarity or explicitly declared as derived-from, and that the intent is to discover connected known entries. It does not dwell on destructive or permission implications, but traversal is clearly a read-oriented operation.

  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, no filler. The core mechanism is front-loaded, and the usage guidance is delivered in the second sentence. Every word 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 graph traversal tool with no output schema and no annotations, the description is nearly sufficient: it explains what is traversed, the two edge types, and why you would use it. A fully complete description might also mention return shape or pagination behavior, but the schema's limit and depth parameters cover the main invocation concerns.

  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 of 3 applies. The description reinforces the meaning of the relation enum by explaining both edge types, but it adds little beyond the schema for id, depth, and limit.

  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 names the exact operation ('traverse the cache graph outward') and the resource ('one entry'), and distinguishes it from sibling CRUD/search tools by focusing on graph connectivity. It also names the two edge types, making the tool's function concrete and 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 a clear use case: pull in everything already known to connect to a cached result. It stops short of explicitly naming alternatives or saying when not to use it, but the graph-traversal framing effectively separates it from cache_get, cache_set, and cache_query.

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

• cache_getA
  4.3/5.0
  Behavior4/5

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

  With no annotations and no output schema, the description carries the behavioral burden and does it well: it discloses exact-match semantics, the hit:false miss/expired case, and the fresh vs stale distinction. It could be slightly more explicit about the shape of a hit:true response, but the freshness semantics go beyond what the schema reveals.

  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?

  Four sentences, all of which contribute: exact-match semantics, when to call, what to do on miss, and freshness handling. It is slightly dense but not wasteful, and the most important usage directive 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 cache lookup with no annotations and no output schema, the description gives the essential runtime semantics: miss behavior, expired-entry behavior, and fresh/stale handling. It could explicitly state the hit:true payload yields the cached response and mention alternatives like cache_query for non-exact lookups, but overall it is complete enough to invoke correctly.

  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 all three parameters with 100% coverage, so the baseline is 3. The description adds value by explaining that model, prompt, and params together form the cache key for an exact match, which connects the parameters to the tool's behavior.

  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 and resource: 'Look up a cached LLM response by exact (model, prompt, params) match.' The exact-match qualifier and the HTTP cache analogy clearly define what the tool does and how it differs from sibling tools like cache_set or cache_query.

  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 tells the agent to call this 'BEFORE issuing an expensive prompt' and instructs what to do on a miss: run the prompt and store with cache_set. It lacks explicit comparisons to cache_query or cache_related, so it does not fully differentiate all sibling alternatives, but the core usage context is clear.

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

• cache_setA
  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 full behavioral burden, and it discloses non-obvious behavior: automatic similarity-graph linking, its effect on cache_related and cache_query, and cascade invalidation via derived_from. It stops short of stating duplicate-key behavior, return values, or key composition, but the main side effects are covered.

  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?

  Four sentences, each earning its place: purpose, usage timing, automatic linking behavior, and derived_from semantics. The most important action is front-loaded and no filler is present.

  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 covers the critical workflow (post-miss write, graph linkage, cascade invalidation) well enough for an agent to invoke correctly with the required fields. Missing return-value expectations and duplicate-handling behavior are minor gaps given the absence of an output schema, but the core context is solid.

  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 50%, and the description adds real meaning for derived_from (parent/cascade relationships). However, tags and the free-form params object receive no guidance, and the description does not compensate for those undocumented parameters. Optional fields like ttl_seconds rely entirely on the schema's default notes.

  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 'Store a prompt/response pair in the cache' states a specific verb and resource, and the references to cache_get, cache_related, and cache_query clearly situate it among the sibling tools. An agent can immediately distinguish this write operation from the read/query/invalidate siblings.

  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 explicitly instructs when to call: 'AFTER getting a fresh response from a model that cache_get did not have,' which names the triggering condition and the primary alternative (cache_get). The derived_from guidance adds a conditional usage rule for derived entries, leaving little ambiguity about when this tool is appropriate.

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