Server Quality Checklist

Tool Scores

• diffB
  3.2/5.0
  Behavior2/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 mentions that the tool reports where versions are held and points to as_of for retrieval, but it does not disclose read-only status, permissions, side effects, or any error 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 a single sentence that is reasonably concise and front-loaded with the core purpose. However, the colon-and-comma structure makes it slightly convoluted and could be clearer.

  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?

  With no output schema or annotations, the description needs to convey the return behavior and workflow. It partially does by mentioning versions and locations, and instructing retrieval via as_of, but it does not describe the output format or handle edge cases like no changes between dates.

  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 references work, from_date, and to_date in the context of comparing changes, but it does not add any semantics beyond the schema, and the optional 'language' parameter is not mentioned.

  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 tool reports what changed between two dates for a given work, including which versions applied and where texts are held. However, it lacks an explicit verb like 'returns' or 'compares', and does not explicitly distinguish itself from sibling tools like timeline or changes_in_period.

  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 provides an implied workflow: use diff to see changes, then retrieve texts via as_of. It does not explicitly state when to use diff versus alternatives like timeline or changes_in_period, and offers no exclusion criteria.

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

• coverageB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden. It discloses that output is organized by tier and includes positive and negative coverage information, but it doesn't mention any operational details like response format, pagination, or data source limitations. This is adequate for a simple read tool but not rich.

  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 tightly written sentences. The first lists key output categories, the second underscores the gap-reporting purpose. No filler.

  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 no output schema and one optional filter, the description gives useful context but leaves open the output structure and the meaning of 'tier' and 'history_begins.' It is sufficient for basic understanding but not fully specified.

  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 single parameter publisher is fully described in the schema as an optional publisher id. The description adds no additional semantics for how filtering works, so the baseline of 3 applies.

  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 the tool reports coverage information ('what we hold and what we lack, tier by tier') and enumerates specific output dimensions (counts, date ranges, history_begins, known gaps). It clearly distinguishes this from sibling tools focused on history, diffs, or searches, though it doesn't explicitly name an alternative.

  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?

  No guidance is provided on when to use this tool versus siblings like provenance or diff. The statement 'This tool exists to say what we do NOT have' implies a gap-analysis use case, but there are no explicit alternative references or preconditions.

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

• timelineB
  3.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 of behavioral disclosure. It does reveal that the tool relies on publisher-asserted data and returns validity intervals and version keys, indicating a read-only operation. However, it does not discuss ordering, pagination behavior, or how to interpret the intervals, leaving gaps in 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 a single sentence with a clear structure: a subject ('Every state a document has been in'), a colon explaining the contents ('validity intervals and version keys'), and a qualifier ('publisher-asserted'). Every word contributes to the meaning, with no redundancy or filler.

  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 is concise but covers the core output type and data source. However, without annotations or an output schema, and given the presence of several sibling tools, the description does not fully clarify how this timeline differs or what a 'state' entails. It is adequate but leaves room for interpretation.

  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?

  All three parameters (work, limit, offset) have schema descriptions, giving 100% coverage, so the baseline is 3. The tool description adds no parameter-specific meaning; it only provides high-level context about the output. Since the schema already documents the parameters clearly, the description does not need to compensate.

  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 communicates that the tool returns the historical states of a document, specifying validity intervals and version keys, and notes the data is publisher-asserted. Though it lacks an explicit verb like 'list' or 'retrieve', the phrase 'Every state a document has been in' clearly implies the function. It distinguishes itself from siblings by focusing on temporal states and version keys, though it does not explicitly name any alternative tool.

  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 sibling tools such as provenance or as_of. The only usage hint appears in the schema's 'work' parameter ('Unknown document -> call search first'), but that is part of the structured parameter description, not the tool description itself. No alternatives or exclusions are mentioned.

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

• provenanceA
  3.6/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 content of the proof chain (source URI, hashes, signatures), which implies a read-only verification operation, but it does not explicitly state that it is non-mutating or describe any potential side effects, errors, or prerequisites.

  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, well-structured sentence that front-loads the core purpose ('Proof chain for one lex_id') before listing details. Every word earns its place with no redundancy or unnecessary fluff.

  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?

  Since there is no output schema, the description compensates by listing the key elements returned (source URI, hashes, event chain, corpus commit, stamp signature). It is complete for a simple lookup tool, though it omits error or performance context and assumes the agent understands 'proof chain' terminology.

  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 input schema already describes both parameters, and coverage is 100%. The description adds that it is for 'one lex_id' and enumerates output components, but it does not elaborate on the 'language' parameter beyond what the schema says ('optional'), so it adds minimal extra meaning.

  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 provides a 'Proof chain for one lex_id' and enumerates the specific components returned (source URI, hashes, event chain, etc.). This distinguishes it from sibling tools like timeline or diff, which serve different purposes.

  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 implies this is for a single lex_id, but it provides no explicit guidance on when to use this tool versus alternatives like article_history or coverage. There are no usage examples, conditions, or exclusions mentioned.

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

• in_force_onA
  4/5.0
  Behavior4/5

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

  Since no annotations are provided, the description carries the behavioral disclosure burden. It discloses that the set is computed at query time from validity intervals, deduplicates by work, and carries a mandatory population disclosure. However, it does not explicitly state side effects or safety profile, though the read-only nature is implied.

  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 with no wasted words. It front-loads the core purpose and adds the key behavioral nuances in a compact format.

  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 query tool with 5 parameters and no output schema, the description adequately explains the core behavior, including deduplication and the mandatory population disclosure. It doesn't detail the response shape, but that is not required when no output schema exists and the tool's purpose is clear.

  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 input schema already provides descriptions for all 5 parameters, achieving 100% coverage. The description adds no additional parameter-specific details but sets the context that the 'date' parameter is central. With full schema coverage, the baseline score of 3 is appropriate.

  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 defines the tool's function: it returns the set of works in force on a date, computed from validity intervals and deduplicated by work. This is specific enough to distinguish it from siblings like 'as_of' or 'timeline' which deal with different temporal queries.

  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 explicitly state when to use this tool over alternatives, nor does it mention exclusions. The usage is implied by the semantics: if you need works active on a specific date, this is the tool, but no direct comparison to sibling tools is provided.

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

• cited_byA
  4.1/5.0
  Behavior4/5

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

  No annotations exist, so the description carries the full burden. It discloses a key behavioral trait: "captured at derive time," indicating the data is a snapshot rather than real-time. It also explains the underlying mechanism (reverse of publisher cross-references), giving insight into what results include. However, it does not explicitly state read-only behavior or response format, though the query-like semantics imply safety.

  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 two sentences, front-loaded with the core purpose. The second sentence adds valuable behavioral and usage context, though the closing phrase "the question legal research is actually made of, and the one a search box cannot answer" is a rhetorical flourish that could be trimmed. Overall, it is appropriately sized and well-structured.

  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 lack of output schema and annotations, the description does a good job explaining the tool's purpose, behavior, and use cases. It clearly indicates the output is a list of citing articles, but does not specify exact response fields or pagination details. For a moderate-complexity lookup tool, this is nearly complete but could be enhanced with response structure notes.

  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% (both 'work' and 'limit' are described in the schema), so the baseline is 3. The description adds conceptual context about what "cited" means, but does not add parameter-specific details beyond the schema, such as how limit behaves or whether work accepts multiple formats.

  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 "Which ARTICLES point at this law," a specific verb+resource pairing that clearly states the tool's function. It distinguishes itself from search by noting "the one a search box cannot answer" and differentiates from sibling tools by emphasizing the reverse nature of citations.

  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 use cases: "answers 'what depends on this law', 'who amended it', 'is anything still referring to it'." It implicitly contrasts with search, but does not explicitly mention sibling alternatives or exclusion criteria, so it has clear context without formal exclusions.

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

• article_historyA
  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 full responsibility for behavioral disclosure. It discloses that renumbering is detected mechanically by identical text hash, and mentions validity intervals and lifecycle events. This goes beyond a simple 'get history' and provides meaningful behavioral detail, though it does not cover error conditions or response shape in depth.

  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, well-structured sentence that front-loads the core function and includes a clarifying question. Every phrase adds value, and there is no repetition or fluff.

  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?

  Despite lacking an output schema, the description explains what the tool returns (distinct texts, validity intervals, lifecycle events) and why to use it. It does not detail the exact output structure, but it gives enough context for an agent to understand the tool's purpose and invoke it correctly given the parameter descriptions.

  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 both parameters (work and anchor) with descriptions, and the tool description does not add additional parameter-level detail beyond mentioning 'article/annex' which is already in the anchor description. Since schema description coverage is 100%, a baseline of 3 is appropriate.

  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: it returns every distinct text a provision has had along with validity intervals and lifecycle events. It directly answers the question 'what did Article X say over its life / when did it change', distinguishing it from related tools like as_of or diff by focusing on historical versions.

  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 usage context: use this tool when you need the history of a provision's text or to know when it changed. It does not explicitly reference alternative tools or exclusions, but the 'answer to...' wording gives a clear when-to-use signal.

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

• as_ofA
  4.4/5.0
  Behavior4/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 clearly states 'Pure lookup, no ranking' and discloses the behavior of each mode, plus that every provision carries a permalink and hash. It doesn't mention edge cases like unknown documents, but that is covered in the parameter description.

  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, front-loaded with the core purpose and then structured details. 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 read-only lookup with no output schema, the description covers the core behavior, modes, and a notable output feature (permalink/hash). It doesn't explicitly address error handling or pagination, but given the tool's simplicity and the rich parameter descriptions, it is sufficiently 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 coverage is 100%, but the description adds value by explaining the mode semantics and the default behavior, which goes beyond the schema's simple enum list. It also reinforces the meaning of anchors for select mode.

  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: 'The state of one document as it stood on one date.' This clearly distinguishes it from sibling tools like timeline or in_force_on by emphasizing a snapshot at a specific point in time. The explicit 'Pure lookup, no ranking' further separates it from search.

  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 guidance on when to use each mode: 'use it first on long documents' for outline, and describes select vs full. It implies this is for point-in-time lookup rather than search or diff, though it doesn't explicitly name alternative tools or exclusions.

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

• searchA
  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 full burden. It discloses the filter-then-rank order, the absence of body text in results, the specific fields returned, and the as_of behavior for full state. This is meaningful behavioral context beyond a generic 'search' claim, though it doesn't mention side effects (none expected for a read-only operation) or pagination details.

  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 core purpose and immediately followed by the most critical behavioral and output details. Every clause earns its place; no fluff or repetition of schema fields.

  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?

  Without an output schema, the description adequately explains the return shape (lex_id, dates, snippet, hash) and the as_of option. It covers the main behavior for a search tool, though it doesn't mention default limit behavior or snippet generation details—but these are minor and largely inferable from the schema. Overall, it is complete for practical use.

  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 100%, so baseline is 3. The description adds value by explaining that filters ('works', 'publisher', 'document_type') run before ranking, and by linking 'as_of' to full state retrieval. This enriches the schema's bare parameter descriptions, justifying a score above baseline.

  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 identifies this as a full-text search tool with a specific pipeline ('filtered-then-ranked') and distinct output (hits without body text, listing exact fields). This distinguishes it from siblings like provenance, timeline, and diff, which serve different purposes.

  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 usage for full-text search needs and clarifies that filters always run before ranking, which informs query construction. It also notes 'Full state via as_of,' guiding users to the as_of parameter for historical state, though it doesn't explicitly mention when not to use this tool or name alternative tools.

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

• changes_in_periodA
  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 transparency burden. It discloses ordering behavior (by_churn ranks by number of new versions; by_date lists most recently changed first) and mentions aggregate output. However, it doesn't explicitly state read-only nature or any side effects, though it's implied as a query 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 concise sentences front-load the core purpose, provide usage examples, and clarify key parameter behavior. No wasted words.

  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 7-param tool with no output schema, the description covers the core output (works, version counts, dates), order semantics, and example use cases. It doesn't describe pagination defaults or return format in detail, but the schema covers limit/offset and the output is intuitive.

  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 covers all parameters, but the description adds meaning for 'order' by explaining what each value does: 'by_churn ranks by number of new versions; by_date (default) lists most recently changed first'. This goes beyond the schema's simple enum description.

  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+resource: 'which works gained new versions between two dates, how many each, and when'. It explicitly contrasts with diff/timeline as the 'aggregate counterpart', distinguishing it 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 Guidelines5/5

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

  The description explicitly says when to use this tool vs alternatives: 'the aggregate counterpart of diff/timeline (which cover ONE work)' and provides concrete example queries ('what changed between 2025 and 2026'). This gives clear guidance on appropriate usage.

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