Server Quality Checklist

Tool Scores

• case_getA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns a summary (counts and identifiers) rather than the full ledger, and clarifies that sources represent distinct skills for corroboration. This meaningfully goes beyond the annotations.

  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 uses compact labeled sections — [READ], WHEN, RETURNS — and front-loads the core purpose. Every sentence earns its place, including the clarification of the sources field, which prevents misinterpretation of the return value. There is no filler.

  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 single-parameter, read-only tool with no output schema, this description is complete: it states when to use it, what it returns, what it intentionally omits, and how the case_id is obtained. The returning field list plus the sources clarification gives the agent everything needed to correctly invoke and interpret the tool.

  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%, and the schema already explains that case_id comes from case_open or case_list and that an unknown id is an error. The tool description adds little beyond reaffirming that the tool reads one specific case, so it does not materially improve on the schema's parameter documentation.

  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 '[READ] One case' — a specific verb, a clear resource, and the scope of what is returned (scope, ledger sizes, grade history). This distinguishes it from siblings like case_list, which would list multiple cases, and case_open, which would open a case for full evidence.

  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 WHEN clause is explicit: use this tool to pick up an investigation or understand why a case has its current grade. It also gives a when-not by stating that this returns counts and identifiers, not the full ledger, and directs the agent to the case folder via the path from case_open for full evidence bodies.

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

• case_knowledgeA
  4.5/5.0
  Behavior5/5

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

  Beyond the readOnly/idempotent annotations, the GOTCHAS section discloses crucial interpretation rules: decisive status requires an applies_to check against case scope, matching is by version applicability rather than similarity, and unanswerable constraints are not passes. This prevents the agent from drawing false conclusions from returned data.

  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 front-loaded with a one-line summary, then organized into WHEN, RETURNS, and GOTCHAS sections. Every sentence carries high-value information without padding or repetition of the schema.

  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?

  With no output schema, the description shoulders the burden of explaining return values, and it does so thoroughly by listing the return fields, explaining format types and conversion needs, and adding key gotchas. The tool behavior is fully specified for an agent to invoke and interpret correctly.

  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 the optional case_id parameter with 100% coverage, including what happens when it is provided. The description's mention of 'plus {applicable, decisive_here} when a case_id is given' reinforces the schema but adds little beyond it, 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 opens with '[READ] What the knowledge layer accepts, and what is mounted,' which names a specific read operation and resource. The RETURNS and GOTCHAS sections further clarify that this tool inventories knowledge formats and version-checks mounted entries, clearly distinguishing it from sibling case-management 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 WHEN section gives concrete situations: when someone asks what can be added to strengthen conclusions, or when a case cannot reach Confirmed and an actionable explanation is needed. It stops short of naming alternatives or explicit when-not-to-use conditions, so it earns a 4 rather than a 5.

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

• case_listA
  4.5/5.0
  Behavior5/5

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

  Beyond the readOnly/idempotent/destructive annotations, the description discloses the exact response envelope, item fields, newest-first ordering, and the damaged-folder behavior where a case appears with state='unreadable' rather than disappearing. This is substantive behavior an agent could not infer from annotations or the tool name.

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

  Conciseness5/5

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

  The description is compact and well-structured: a front-loaded [READ] tag and main action, a WHEN usage note, and a terse return-shape description. The unusual unreadable-state edge case earns its own sentence without bloating the text.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a one-optional-parameter list tool with no output schema, the description covers everything an agent needs: purpose, ordering, response shape, pagination-related fields, and an important edge case. Since there is no output schema, including the return envelope in the description is essential and it is present.

  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 only parameter, limit, is fully documented in the input schema, including its default, ordering, and the lack of an offset. The description adds no additional parameter-level meaning beyond what the schema already provides, so the baseline 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 opens with '[READ] List investigation cases, newest first' — a specific verb and resource that distinguishes this from case_get and other sibling case tools. The WHEN note further clarifies the intent by tying it to finding the id of a previously opened case.

  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 explicit 'WHEN' clause tells the agent to use this tool when it needs the id of an earlier-opened case, which is clear and actionable. It does not explicitly name alternatives or state when not to use it, such as pointing to case_get for full case details, so it stops just short of full routing guidance.

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

• case_planA
  4.5/5.0
  Behavior5/5

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

  Goes well beyond the annotations by disclosing recomputation behavior, the non-checklist nature, how plan length changes, and what happens when sources are lost. It also explains the meaning of unavailable, empty steps, and category_signas — all without contradicting the readOnly/idempotent annotations.

  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?

  Uses clear section headers (WHEN, RETURNS, GOTCHAS) and front-loads the core purpose. Despite its length, each sentence adds distinct behavioral or return-value value with no fluff or repetition.

  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?

  Her the absence of an output schema, the description fully specifies the return object shape, key nested fields, edge cases, and follow-up flow. An agent has enough to call it and interpret results correctly in context.

  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 schema already fully documents all parameters. The description reinforces category inference behavior and return-field mechanics but does not need to add parameter meaning; baseline 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?

  States a precise function: 'What to fetch next for this case' with a clear phase marker ('step 02'). It also distinguishes itself from the submission tool by naming the follow-up action, making its role unambiguous among siblings.

  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?

  Gives explicit timing guidance: 'right after case_open, and again after each round of evidence' and explains what changes the next plan. It stops short of naming explicit when-not-to-use alternatives, but the sequencing is clear enough to route an agent.

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

• case_readinessA
  4.5/5.0
  Behavior5/5

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

  The description goes well beyond the readOnly/idempotent annotations by explaining non-obvious behavior: unmatched skills are returned in unrecognised_skills instead of being treated as absent, two classes served by the same skill count as one source, hardware is always unavailable, and knowledge requires a specific mount path. These are exactly the kind of gotchas an agent needs to interpret results correctly.

  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 structured with clear labels (READ, WHEN, RETURNS, GOTCHAS) and is front-loaded with its core purpose. Every section adds necessary decision-making or behavioral detail, and no sentence is filler or redundant.

  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 there is no output schema, the RETURNS section sufficiently explains the response shape and semantics, while GOTCHAS covers the edge cases that would otherwise surprise a caller. The tool is simple enough (one optional parameter) and the description fully equips an agent to invoke it correctly.

  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 the single parameter 100% with a rich description including spelling variants and the omission behavior. The main description reinforces the unrecognised_skills semantics and adds the 'same skill counts as one source' caveat, but most of the parameter meaning is already in the schema, 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 starts with a precise question: 'What strength of conclusion can this environment reach?' and distinguishes this readiness assessment from the sibling tools by stating it is used before an investigation begins. It clearly identifies the resource (environment conclusion strength) and the analytical output it provides.

  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 WHEN clause explicitly states two concrete situations: before starting an investigation, or when a case will not go higher and you need to know if that is fixable. This gives clear contextual guidance, though it does not explicitly name alternative tools or state when not to use it.

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

• case_record_gapA
  4.5/5.0
  Behavior5/5

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

  The description adds meaningful behavioral context beyond the annotations. It discloses the return shape {case_id, gap_id, grade, reasons} and the important grading effect: recording a gap caps the grade but does not demote it, and writing gaps down is 'meant to be free.' This is valuable non-obvious behavior.

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

  Conciseness5/5

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

  The description is compact, clearly sectioned with WHEN, RETURNS, and GOTCHAS, and every sentence carries useful information. The core purpose is front-loaded, and there is no redundant filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The definition covers when to use the tool, what it returns, and the key behavioral gotchas about grade impact. The schema documents all parameters with strong descriptions, including how to reference existing hypotheses and what could_falsify means. No critical information appears missing for an agent to invoke this correctly.

  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 schema already documents each parameter well. The description provides general context for the tool's purpose but does not add specific meaning about individual parameters beyond what the schema already gives. Baseline 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 opens with a specific verb and resource: 'Record something the investigation could NOT obtain.' It clearly distinguishes this from evidence-recording tools by emphasizing that the data was not obtainable, and the 'keeps a case honest' framing reinforces the unique purpose among siblings.

  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 an explicit WHEN section: 'any time a fetch failed, was refused, returned nothing, or the data simply does not exist in this environment.' It clearly communicates when to use the tool, though it does not explicitly name the alternative evidence-recording tool such as case_submit_evidence or state when not to use it.

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

• case_submit_evidenceA
  4.5/5.0
  Behavior4/5

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

  The description discloses write intent ('[WRITE]'), the returned grade so no second call is needed, and the behavior of payload interpretation (payload_events/payload_note) and timeline visibility. Annotations only provide readOnly/openWorld/idempotent/destructive hints; the description adds meaningful behavioral context without contradicting them.

  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 organized into labeled sections (WRITE, WHEN, RETURNS, GOTCHAS) and front-loads the core action. Every sentence adds information, and there is no redundant re-statement of the schema.

  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 13-parameter write tool with no output schema, the description covers the essential missing context: output shape and meaning, when to call it, and the one critical exception. The schema handles parameter-level details, so the whole package is complete enough for correct invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents all 13 parameters in detail. The description adds only general payload/summary semantics, such as a summary submitted in place of a result being visible in the payload note, and does not need to repeat parameter definitions. Baseline 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 opens with '[WRITE] Record one retrieved fact' — a specific verb and resource — and labels it as steps 02/03 of the evidence loop. It also names the sibling it is not: 'a fetch that failed or came back empty goes to case_record_gap, not here.'

  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?

  'WHEN: after every read-tool call you intend to reason from' gives an explicit trigger condition. The GOTCHAS section provides the exclusion case: failed or empty fetches belong in case_record_gap, not here. This tells the agent both when to use the tool and when to route elsewhere.

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

• case_openA
  4.6/5.0
  Behavior5/5

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

  Annotations indicate a non-read-only, non-idempotent, non-destructive operation, and the description adds meaningful behavioral detail: it writes only under $OPS_HOME, never touches a VMware system, and never overwrites an existing case. It also reveals that the return value contains a ceiling grade and advises reading it immediately, which is valuable runtime guidance.

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

  Conciseness5/5

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

  The description is compact and well-structured with labeled sections: [WRITE], WHEN, RETURNS, and GOTCHAS. Every section earns its place, and the most important decision guidance 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?

  The description covers when to use the tool, return shape, a critical return-value caveat, and key behavioral constraints. Since there is no output schema, a bit more detail on fields like path, state, grade, and next would have made it fully self-contained, but the provided guidance is sufficient for an agent to call the tool correctly.

  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%, with rich parameter descriptions already covering summary, determined_by, window_start, and product_versions. The tool description itself does not add parameter-level detail, so the baseline score of 3 is appropriate; the schema already does the heavy lifting.

  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 '[WRITE] Open an investigation case — step 01, define the event,' naming a specific action and resource. It clearly establishes this as the starting point for a reasoned investigation, which distinguishes it from lookup and read tools like incident_timeline and case_get.

  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 WHEN section explicitly states the intended situation: 'at the start of an incident you expect to reason about rather than glance at.' It also names the alternative for a different context: 'For a one-off lookup use incident_timeline alone.' This gives the agent an explicit routing rule.

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

• case_closeA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations, the description reveals finality and side effects: the case becomes a permanent record, 'a closed case is not closed again and its record is never rewritten.' It also discloses the output shape and the meaning of open_gaps, which is especially useful because there is no output schema. No statement conflicts with the annotations.

  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 compactly sectioned as WRITE/WHEN/RETURNS/GOTCHAS, front-loading the purpose and placing caveats at the end. Every section adds operational value with no filler or redundant restatement.

  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 one-parameter mutating tool with no output schema, this is complete: it states when to call it, what it returns, the meaning of open_gaps, and the irreversibility caveat. The annotations supply the remaining safety profile, so nothing essential is missing for correct 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 schema already covers the single parameter at 100%, including provenance ('from case_open/case_list'), the absence of a grade parameter, and refusal of already-closed cases. The prose reinforces the grade-recomputation behavior but adds no new parameter-specific semantics beyond the schema, so the baseline 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?

  Opens with a clear verb-resource pair: 'Record the final grade and archive the case — step 08.' The description also differentiates the operation by saying it 'computes and records the grade rather than accepting one,' which separates it from grade-related or read-only case tools. This is specific 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 Guidelines5/5

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

  Provides an explicit 'WHEN' section: use it 'when the investigation is finished, or is being handed over.' The GOTCHAS section adds a when-not and an alternative: 'a closed case is not closed again' and to reopen, 'open a new case that cites this one.' This gives agents concrete routing context even though it does not name each sibling tool.

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

• case_gradeA
  4.7/5.0
  Behavior5/5

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

  The description richly discloses behavior beyond the annotations: grades are recomputed, can go down, are appended to conclusion.md and never rewritten, and the default ceiling on a stock install is 'probable' with an explanation of why. This is exactly the kind of behavioral context that helps an agent predict side effects and limits.

  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 longer than usual, but every section earns its place: WHEN, level definitions, RETURNS, and GOTCHAS. It is front-loaded with the core purpose and uses clear section markers, making it easy for an agent to scan and apply.

  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?

  With no output schema, the description compensates by listing exact return fields, explaining the meaning of 'direction,' and documenting the practical ceiling limitation. It also tells the agent how to influence the grade (submit evidence or record a gap), covering the full decision loop around the call.

  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 already documents case_id clearly, and description coverage is 100%, so the baseline is solid. The description adds meaningful context by explaining why there is deliberately no grade parameter and that the grade is derived from the ledger, which prevents an agent from expecting a grade input.

  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 pair: 'Compute and record the conclusion grade — steps 07/08.' It also clarifies a distinguishing design point (no grade parameter; recomputed from ledger) and defines the grade levels, making the tool's purpose unmistakable relative to siblings like case_readiness or case_close.

  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 provides an explicit WHEN section: 'when you think the investigation has reached a conclusion, or to record where it stands before handing it over.' It does not explicitly name sibling alternatives or say when not to use it, but the condition is clear and actionable.

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

• case_timelineA
  4.7/5.0
  Behavior5/5

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

  The description discloses that this is a write operation producing timeline.md, lists the full return object, and explains subtle behaviors around 'note' and 'rejected' that could otherwise mislead analysis. Annotations here are mostly negative/false, so the description carries the transparency burden and handles it thoroughly.

  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?

  Although long, the description is deliberately structured with WHEN, RETURNS, and GOTCHAS sections, and every sentence adds operational value. The front-loaded purpose statement and the clear sectioning make the length justified rather than bloated.

  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 no output schema, the description provides the full return field list, the file side effect, the main failure modes, and the expected input semantics. An agent has enough information to select, invoke, and interpret this tool without further inference.

  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 schema already documents all four parameters well. The description adds useful context about reproducibility and the payload requirement, but does not materially expand on individual parameter semantics beyond what the schema states.

  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 action (correlate everything this case has collected) and explicitly contrasts itself with incident_timeline, which takes events rather than reading from submitted payloads. This makes the tool's scope and its distinction from siblings immediately clear.

  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?

  It gives an explicit WHEN condition ('once evidence is in') and clarifies that unlike incident_timeline, no events should be passed because everything comes from the case folder. It also instructs the agent to submit a read tool's raw result as 'payload', with a warning that summaries carry no rows.

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

• incident_timelineA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context: 'read-only, stateless, no network — nothing is executed,' malformed-event error behavior, and remediation routing. It goes well beyond the annotations without contradicting them.

  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 organized into [READ], WHEN, RETURNS, and GOTCHAS sections, front-loading the core purpose and making every section skimmable. Even though it is longer than average, each sentence carries distinct operational information with no filler.

  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?

  There is no output schema, so the detailed RETURNS section is essential and covers the full return shape, including spikes, hypotheses, next_checks, and caveats like reading binning and classification. Combined with schema, annotations, and edge-case handling, nothing an agent needs to invoke and interpret this tool is missing.

  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%, and each parameter (events, bin_seconds, z_threshold, top_n) already has a thorough schema description including defaults and edge-case behavior. The tool description adds no additional parameter-level meaning 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 opens with a specific verb and resource: 'Correlate already-fetched VMware events into one incident view.' It clearly distinguishes this tool from data-fetching skills by stating 'This tool does NOT fetch anything itself,' and the scope is unambiguous.

  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 WHEN section explicitly instructs when to use the tool (after pulling events from named data-source skills), what to do if unsure which events to pull (run list_symptom_categories first), and what the tool does not do. This is strong, actionable routing guidance.

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

• list_symptom_categoriesA
  4.9/5.0
  Behavior5/5

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

  Annotations already mark it read-only and idempotent, and the description adds valuable behavior beyond that: the routing table is a fixed constant, truncated is always false, total is exact, this is every category rather than a page, and there is no network access. This gives the agent strong expectations about stability and pagination.

  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?

  Although longer than minimal, every sentence earns its place: role, item contents, use case, downstream workflow, return envelope, and fixed-constant behavior. The description is front-loaded with [READ] and the core listing verb, then supplies only operationally relevant detail.

  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?

  Despite having no output schema, the description fully specifies the return envelope and item shape, explains that results are never paginated, and connects to the sibling tool it feeds. Combined with the rich annotations and zero-parameter signature, an agent has everything needed to select and invoke it 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 tool takes zero parameters and the schema fully documents that with an empty properties object. The description reinforces this by explicitly saying 'Takes no parameters,' which removes any temptation to invent arguments. Baseline for zero-parameter tools is 4; no further elaboration is needed.

  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?

  States a specific verb and resource: lists the symptom categories vmware-debug recognises, and specifies that each item carries example keywords and a suggested next check. This clearly distinguishes it from siblings like incident_timeline, which is framed as the downstream consumer of the checks it recommends.

  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?

  Explicitly says to use this when you don't yet know what to look at, turning a vague problem into concrete investigation steps. It also gives the follow-up workflow: gather the events named by the checks and pass them to incident_timeline. This effectively signals when this tool is the right entry point.

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

• case_hypothesesA
  5/5.0
  Behavior5/5

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

  Annotations provide almost no behavioral signal beyond non-readonly, so the description carries the full burden. It discloses key behaviors: ids are auto-assigned, unregistered ids are refused rather than ignored, statuses are computed from external evidence/gaps, and refuted outranks blocked. This is rich, non-obvious context an agent needs before calling.

  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 organized into clearly labeled sections — WHEN, RETURNS, GOTCHAS — and every sentence adds functional value. It is longer than average, but the complexity of the dual read/write behavior and derived-status model justifies the length; nothing feels like filler.

  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?

  With no output schema, the description supplies the exact return shape and the meaning of each status. It also explains the refusal behavior for dangling ids and the precedence rule, which are essential for correct use in the broader case-management workflow. The tool is fully usable from the description alone.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Even though schema coverage is 100%, the description adds meaningful semantics: statement is 'one line', omitting it triggers read mode, new hypotheses receive sequential ids, and there is intentionally no status parameter because status is derived. This goes well beyond the schema 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?

  The description opens with a precise dual purpose: 'Register a candidate explanation, or read the ledger' with the resource (hypothesis ledger) clearly named. It differentiates itself from siblings by explaining that hypothesis ids are consumed by case_record_gap and case_submit_evidence, making the tool's role in the workflow unmistakable.

  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?

  WHEN guidance is explicit: use it as soon as a theory is worth testing and again to inspect standings. It also clearly distinguishes the two modes — pass statement to add, omit it to read — and explains how ids connect to sibling tools, so an agent knows exactly when and how to invoke it.

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