Server Quality Checklist

Tool Scores

• get_sceneA
  3.5/5.0
  Behavior4/5

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

  The description provides behavioral context beyond the readOnlyHint annotation by explaining that the tool aggregates across catalogues, shows which catalogue contributed each value, discloses how disagreements are handled (the 'nobody preferred' reading published beside the winner), and notes that 'sources' restricts to one catalogue. This adds meaningful behavioral detail, though the phrasing is convoluted.

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

  Conciseness3/5

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

  The description is only three sentences, but they are densely packed and use awkward, non-standard phrasing (e.g., 'the reading nobody preferred'). It lacks front-loading of the core purpose and uses more words than necessary to convey the aggregation and conflict behavior.

  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 aggregation and conflict resolution behavior, the description covers the main concepts but is cryptic. It doesn't explain the 'prefer' and 'sections' parameters, and the existing prose may confuse more than clarify. An output schema exists, so return values are covered elsewhere, but the description itself leaves gaps for a smooth invocation.

  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 description adds meaning for the 'id' parameter (identifying the scene as instance:uuid) and the 'sources' parameter (read one catalogue alone). However, it does not mention the 'prefer' or 'sections' parameters. With schema coverage at 50%, the description partially compensates but leaves important parameters undocumented in prose.

  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 'Read one scene' and the resource (a scene identified by an instance:uuid), distinguishing it from search_scenes which searches. However, the phrasing 'from the catalogue its identifier names' is awkward, making it slightly less clear than a straightforward 'retrieve a single scene by ID'.

  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 when you have a specific scene identifier (read one scene), but it does not explicitly compare to alternatives like search_scenes or get_sources. It does mention using the 'sources' parameter to read one catalogue alone, which is parameter-level guidance, not tool-selection guidance. Overall, usage context 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.

• get_performerA
  3.8/5.0
  Behavior4/5

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

  The description adds meaningful context beyond the annotations: it explains that the tool merges records from multiple catalogues, presents disagreement resolution ("where they disagree the reading nobody preferred is published beside the one that won"), and the 'prefer' parameter's effect. While annotations declare readOnlyHint=true and openWorldHint=true, the description's catalogue-merge explanation is distinctive. However, the phrasing is obfuscated — terms like 'card', 'reading', and 'nobody preferred' are used in non-standard ways without being explicitly defined.

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

  Conciseness3/5

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

  The description is a single dense paragraph that is somewhat RAMBLING. The first sentence introduces the core purpose, but the subsequent three sentences are long, nested, and contain an extended metaphor that requires significant cognitive overhead. Some sentences are 40+ words and include unusual phrasings like 'the answer is one card, read on every catalogue that holds the record and reached by the link each of them publishes to the same record elsewhere.' The entire description could be more concise with clearer, plainer language, lending to a lower score on structure.

  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 no output schema, the description makes a fair effort. It explains the merged-catalogue output, the role of the 'prefer' parameter in resolving disagreements, and the semantics of the 'sources' parameter. The tool's complexity is medium, given the merge logic. The description doesn't lack for explaining the returned data; the main issue is the overly florid language which, while adding context, requires effort to parse. Given the presence of an output schema (as evidenced by 'Has output schema: true'), the threshold for completeness is lowered.

  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?

  With 50% schema coverage, the description partially helps: it explains the 'sources' parameter and mentions the 'prefer' ordering, but it doesn't cover the 'sections' parameter at all and describes 'id' only by example ('instance:uuid'). The 'prefer' parameter is mentioned but not by name. The id parameter's uuid format is partially covered by the schema's pattern, and the description adds the notion of a qualified instance:uuid. This adds some value but doesn't fully compensate for the 50% coverage gap, hitting the baseline of 3.

  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 begins with a specific transitive verb and object: "Read one performer from the catalogue its identifier names, written instance:uuid." This clearly states the tool retrieves a single performer by ID, distinguishing it from siblings like search_performers (which searches). However, the sentence is grammatically awkward ('catalogue its identifier names'), and the latter half of the description shifts into a confusing metaphor about cards, catalogues, readings, and disagreements that obscures rather than clarifies the tool's core purpose.

  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 explicitly contrasts with the alternative 'sources' parameter: "Name 'sources' to read one catalogue alone." This tells users when to use the sources parameter versus the default merged view. While it doesn't explicitly name sibling tools like get_sources, it clearly explains the two modes of operation. However, it doesn't explicitly say when to prefer this over search_performers, though the read-vs-search distinction is implied.

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

• get_studioA
  3.8/5.0
  Behavior4/5

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

  The description adds behavioral detail beyond the readOnlyHint and openWorldHint annotations, explaining how disagreements between catalogues are handled and how sources can limit reads. It discloses the aggregation behavior and preference logic, which annotations don't provide.

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

  Conciseness3/5

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

  The description is a single long sentence with complex phrasing, making it harder to parse. It packs information but lacks clear structure or front-loading of key details.

  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 explains the core read behavior, conflict resolution, and sources limitation, which is substantial for a read tool with an output schema. It doesn't detail output format, but the output schema likely covers that, so the description is reasonably complete.

  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 covers only 'prefer' with a description, while 'id' and 'sources' lack descriptions. The description explains 'id' format (instance:uuid) and 'sources', but 'prefer' semantics are already in schema. With 33% coverage, description partially compensates but doesn't fully detail 'sources' usage beyond a brief mention.

  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 states it reads one studio from the catalogue by identifier, which is a specific verb and resource. However, it doesn't explicitly distinguish from siblings like get_scene or get_performer, though the distinct resource (studio) is clear.

  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 the tool is for reading a single studio given an ID, and it mentions the 'sources' parameter to read from one catalogue alone, giving some usage context. It doesn't explicitly rule out alternatives, but the context of studio reading is clear.

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

• search_tagsA
  3.8/5.0
  Behavior4/5

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

  The description adds behavioral details beyond the readOnly and openWorld annotations: it explains the exclusive query/typed-argument modes, that mixing them is refused, the per-catalogue response statuses, and that counts are never aggregated. While oddly phrased, these are meaningful and do not contradict annotations.

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

  Conciseness2/5

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

  The description is short but not concise in meaning. Phrases like 'a catalogue nobody asked, and an emptiness it established' are cryptic and obscure the intended behavior. The front-loaded purpose is clear, but the subsequent wording is convoluted and could be made more direct.

  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's complexity (8 optional parameters, exclusive modes, multi-catalogue behavior), the description covers the main paths and response characteristics. However, it leaves gaps such as what happens with no parameters, the meaning of the 'sources' parameter, and the precise interpretation of the three statuses. The presence of an output schema covers return values, so this is only moderately 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?

  Schema description coverage is only 38%, so the description compensates by explaining that 'query' uses each catalogue's text index with union semantics, while typed arguments narrow as an intersection, and that the two are mutually exclusive. This gives group-level meaning to structured parameters, though individual parameters like name and category_id are not further clarified.

  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 'Search tags across every configured stash-box catalogue,' which clearly identifies the verb (search), resource (tags), and scope (all catalogues). This distinguishes it from sibling tools like search_scenes, search_performers, or get_tag.

  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 this is the tool for searching tags across all catalogues, but it does not explicitly state when to use this tool versus alternatives like get_tag. It does provide internal usage constraints by explaining the two exclusive paths and that mixing them is refused, which guides invocation but not tool selection.

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

• get_tagA
  3.9/5.0
  Behavior5/5

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

  The description adds significant behavior beyond the readOnlyHint and openWorldHint annotations: it explains that results are read across every catalogue holding the record, that each value names its source catalogues, that disagreements surface the non-preferred reading alongside the winner, and that sources restricts reads to one catalogue. No contradiction with annotations.

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

  Conciseness3/5

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

  The description is not overly long and front-loads the core action, but the prose is dense and grammatically awkward ('the catalogue its identifier names', 'reached by the link each of them publishes'), which hurts readability. It could communicate the same behavior in clearer, more compact language.

  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 multi-catalogue read with an output schema and read-only annotations, the description covers the key behavioral wrinkles: cross-catalogue resolution, per-value provenance, disagreement handling, and the sources restriction. It does not discuss not-found or error cases, but the main weakness is that the unusual wording obscures rather than clarifies context that is otherwise present.

  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 low (33%), so the description partially compensates: 'written instance:uuid' clarifies the id format, 'Name sources to read one catalogue alone' explains the sources parameter, and the disagreement/preference text gives meaning to prefer. Still, it does not systematically document each parameter, and the prefer behavior is only conveyed indirectly.

  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 opens with 'Read one tag from the catalogue its identifier names, written instance:uuid,' which identifies the action (read) and resource (tag) and indicates lookup by identifier. However, the phrasing is convoluted and could more directly distinguish this from sibling tools like search_tags or get_sources, though the singular 'one tag' helps.

  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?

  Usage is implied by the verb 'Read one tag' and the mention of identifier-based lookup, but the description does not explicitly say when to prefer this tool over alternatives such as search_tags or get_sources. The only direct usage hint is 'Name sources to read one catalogue alone,' which guides a parameter rather than tool selection.

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

• search_studiosA
  3.9/5.0
  Behavior5/5

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

  Annotations only declare readOnlyHint and openWorldHint. The description adds substantial behavioral context: query vs typed-argument exclusivity, refusal when both are written, per-catalogue outcome classification, and no cross-catalogue count aggregation. No contradiction with annotations.

  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?

  Five sentences, front-loaded with purpose, followed by compact behavioral rules. The phrasing is somewhat cryptic ('a failure, a catalogue nobody asked, and an emptiness it established') but every sentence contributes meaningful information without padding.

  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 complex tool with 9 parameters, two search modes, and an output schema, the description covers the essential behavioral complexity: exclusivity, per-catalogue results, and count handling. It leaves some parameter semantics to the schema and lacks tool-selection context, but overall it is adequate and useful.

  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 only 33% (3 of 9 parameters). The description adds important semantics for query (union), typed arguments (intersection, exclusivity), and per-catalogue page/limit behavior. However, it does not explain name, sort, direction, parent_id, has_parent, or sources beyond what schema enums and patterns already imply.

  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 'Search studios across every configured stash-box catalogue' – a specific verb, resource, and scope. This clearly distinguishes the tool from sibling searches for scenes, performers, and tags, and from get_studio.

  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 explains internal usage rules ('Two exclusive paths', 'Writing both is refused') but gives no guidance on when to choose this tool over alternatives like get_studio for exact IDs or search_scenes for scene queries. It neither names alternatives nor states exclusions.

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

• search_performersA
  4.2/5.0
  Behavior5/5

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

  Annotations (readOnlyHint: true, openWorldHint: true) already establish safety and open-world semantics. The description goes well beyond, revealing exclusive paths, the refusal when both are written, per-catalogue response states ('a failure, a catalogue nobody asked, and an emptiness it established'), non-summation across catalogues, and the behavior of no-op parameters like alias.

  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?

  Remarkably compact for a description covering such conceptual terrain, front-loading purpose and then detailing behavior efficiently. The unusual phrasing 'a catalogue nobody asked, and an emptiness it established' is striking but slightly confusing without clearer syntax, and the description remains dense yet occasionally opaque, costing it a point.

  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 complex tool with 17 parameters, multi-catalogue fan-out, and exclusive query modes, the description captures the critical behaviors—union vs intersection semantics, exclusivity rules, per-catalogue response consistency—that an agent must understand to invoke it correctly. The output schema correctly handles return-value details.

  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 35%, so the description carries a heavy burden. It delivers an excellent conceptual framework explaining 'query' (union) vs typed args (intersection) and exclusivity, but with 10 of 17 parameters undocumented and uncovered by the main description, it cannot fully compensate. The framework elegantly covers the crucial conceptual model without resolving all gaps.

  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?

  'Search performers across every configured stash-box catalogue' precisely states verb, resource, and the distinguishing scope of multi-catalogue search. It clearly differentiates from sibling search tools by stressing 'across every configured stash-box catalogue,' something search_scenes, search_studios, and search_tags would not do.

  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 strong internal guidance on when to use the 'query' path vs typed arguments (union vs intersection, mutually exclusive). It implicitly communicates when to use the tool but never explicitly names alternatives or states conditions for choosing it over get_performer or sibling search tools, leaving the exclusion logic unexplained.

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

• find_by_fingerprintA
  4.3/5.0
  Behavior4/5

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

  Annotations already disclose readOnlyHint and openWorldHint, so the description needs less safety disclosure. It adds behavioral value by stating the search spans every configured catalogue and that each matched record is returned as one card per catalogue that holds it, and it explains the semantic distinction between byte-exact and likeness hashes.

  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 compact and front-loaded with the main action, and it packs useful hash semantics into just three sentences. The wording is somewhat stylized and roundabout ('answered as one card, read on every catalogue that holds it'), but it remains appropriately sized and readable.

  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 output schema exists, the description does not need to detail return record shapes, and it addresses the central behaviors: catalogue-wide scanning, hash algorithm meanings, and per-catalogue cards. It leaves some nuance about the 'sources' parameter implicit, yet the parseable schema descriptions and annotation still make this tool usable without large gaps.

  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 covers about half of the parameters with descriptions, and the description adds meaning beyond it—especially the algorithm semantics: MD5/OSHASH name file bytes, while PHASH captures a re-encode/crop similarity. This helps an agent choose correct fingerprint values, though sources and sections still rely heavily on schema names and the existing descriptions.

  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?

  Description clearly states the tool's function: identify a file/scene from hashes across every configured stash-box catalogue. It uses a specific verb and resource ('identify a file', 'hashes', 'catalogue'), and the fingerprint-based scope distinguishes it from siblings like search_scenes and get_scene.

  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 creates clear context: use this when you have hashes and want to identify a matching file across catalogues, with MD5/OSHASH for byte-exact matches and PHASH for likeness. It does not explicitly name alternatives or say 'use search_scenes instead', so it falls short of a perfect score, but the intended usage is unmistakable.

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

• get_sourcesA
  4.3/5.0
  Behavior4/5

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

  The description adds valuable context beyond the readOnlyHint: it states 'Reaches no catalogue,' clarifying that the tool performs no network calls to external sources. It also explains that the key-holding fact is local and does not affect catalogue behavior, which is useful behavioral transparency.

  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-loads the purpose, and every sentence adds value. The second sentence clarifies an important nuance about key holding without being verbose.

  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 zero-parameter tool with an output schema, the description covers the semantic meaning of the data (what catalogues answer, reading date, location of configuration facts) and explicitly states it reaches no catalogue. This is complete for the tool's 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, and the description explicitly confirms 'takes no argument.' While there's no parameter detail to add, this meets the baseline 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 clearly states what the tool does: it reports what each configured stash-box catalogue was measured answering and the date its surface was read. This is distinct from the sibling search/get tools, which operate on specific entities. The verb and resource are evident.

  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 (e.g., to inspect catalogue capabilities and reading dates) but does not explicitly say when to use this tool versus alternatives. It mentions 'Reaches no catalogue' which hints at safety but lacks explicit exclusions or alternative references.

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

• search_scenesA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat safety. It adds valuable behavioral context: the per-catalogue response structure (failure, nobody asked, emptiness), the refusal of both paths, and the non-aggregation of counts. This goes beyond annotations, though it could mention pagination behavior more explicitly.

  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 concise and front-loaded with the core purpose. It uses clear, structured language to explain the two paths and result semantics. However, some phrasing is slightly convoluted (e.g., 'an emptiness it established'), which could be clearer, but overall it's efficient.

  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 complexity (16 parameters, multiple catalogues, exclusive paths), the description covers the essential behavioral aspects: the two paths, per-catalogue results, and non-aggregation. It doesn't detail every parameter, but the output schema exists and the description focuses on the most critical usage rules. It's adequate for an agent to use correctly, though more parameter-specific guidance would improve completeness.

  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 only 38%, so the description must compensate. It does explain key parameters like query, match, and limit, and clarifies the exclusive nature of query vs. typed arguments. However, many parameters (code, date, title, sources, direction, etc.) lack description-level detail, relying on schema names. The description adds meaning for the most complex interactions but not all.

  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 searches scenes across every configured stash-box catalogue, with two exclusive search paths. It distinguishes itself from sibling tools like search_performers, search_studios, and search_tags by specifying the resource (scenes) and the multi-catalogue scope.

  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 explains the two exclusive paths (query vs. typed arguments) and when to use each, noting that writing both is refused. It also clarifies that counts are never added across catalogues, guiding the agent on how to interpret results. This provides clear usage context and exclusions.

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