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

Annotations already indicate readOnlyHint=false and idempotentHint=false. The description goes beyond by disclosing that the grade is computed from the ledger rather than accepted, that the return includes open_gaps, and that a closed case cannot be closed again and its record is never rewritten. This adds meaningful behavioral context about irreversibility and the computation logic, without contradicting 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.

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

The description is organized into concise, clearly labeled sections (purpose, WHEN, RETURNS, GOTCHAS), front-loaded with the core purpose. Every sentence provides useful information without redundancy. The format makes it easy for an agent to quickly grasp the tool's behavior and consequences.

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

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

The description covers the tool's purpose, trigger condition, output shape, and important gotchas (irreversibility, refusal of already-closed cases, and the alternative for reopening). For a simple single-parameter tool, this is comprehensive and leaves no critical gaps for an agent to make a correct call.

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

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

The input schema for case_id already provides a full description, including that there is no grade parameter and that closing recomputes the grade. The tool description repeats this ('no grade parameter — closing recomputes the grade from the ledger') but does not add new meaning. With 100% schema description coverage, the baseline of 3 is appropriate; the description adds no additional semantic insight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line 'Record the final grade and archive the case — step 08' clearly states the action (record + archive), the target resource (case), and its position in the workflow. It distinguishes itself from siblings like case_grade (which computes grade without closing) and case_open by its finalizing, archiving role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The 'WHEN' section explicitly states to use this tool when the investigation is finished or handed over. It also provides an alternative for reopening ('open a new case that cites this one'), clarifying that closing is a terminal action and not for ongoing work. This is clear usage guidance with both a positive trigger and an exclusion.

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

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 meaningful behavioral context by stating that it returns aggregate counts and identifiers rather than full evidence bodies, and by listing exactly what fields are returned, including grade_history and blocking_gaps.

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

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

The description is tightly structured with READ/WHEN/RETURNS sections, front-loading the core purpose and use case. Every sentence adds value, and the return field list is provided in a compact, scannable format without unnecessary prose.

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

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

For a one-parameter, read-only tool with rich annotations and no output schema, this description is complete. It explains what the tool returns, when to use it, and when to use an alternative, so an agent can correctly select and invoke it without additional context.

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

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

Schema description coverage is 100%, and the single parameter case_id is well documented in the schema, including the note that an unknown id is an error. The description does not add extra parameter semantics beyond the schema, which is acceptable given full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with '[READ] One case' and immediately scopes the tool: 'its scope, its ledger sizes, and its grade history.' It clearly distinguishes itself from sibling tools by noting that it returns counts and identifiers rather than the whole ledger, so an agent can tell this apart from case_open, case_list, or case_timeline.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The 'WHEN' section gives explicit use cases: 'to pick up an investigation, or to see why a case sits at the grade it does.' It also provides a when-not and alternative: 'read the case folder itself (the path from case_open) for full evidence bodies,' which tells the agent exactly when case_get is insufficient.

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

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

The description discloses rich behavioral traits beyond the annotations: the grade is recomputed from the ledger, there is deliberately no grade parameter, grades may go down, every grading is appended to conclusion.md and never rewritten, and stock-install ceiling is 'probable.' This goes far beyond the minimal annotation hints.

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

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

The description is longer than average but is well-structured with WHEN, RETURNS, and GOTCHAS sections, and the content is substantive. The unexplained 'steps 07/08' reference and the lengthy level definitions add some bulk, but the sections make it scannable and front-loaded with the core purpose.

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

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

Given the single parameter and no output schema, the description is remarkably complete: it defines all grade levels, explains the ceiling edge case, details the return fields including direction and hypotheses, and notes the append-only recording behavior. An agent has everything needed to call it correctly.

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

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

The input schema already documents case_id fully, including its source ('from case_open/case_list') and the absence of a grade parameter. The description reinforces this but does not add substantially new parameter-level meaning beyond what the schema covers, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb and resource: 'Compute and record the conclusion grade.' It also ties the action to workflow steps (07/08) and explains what the tool is not doing (accepting a grade parameter), which distinguishes it from evidence-submission and gap-recording siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The 'WHEN' section explicitly states the invocation condition: when the investigation has reached a conclusion or before handover. It also gives alternative actions when the agent disagrees with the computed grade—'submit the evidence that is missing, or record the gap that is blocking it'—which routes the agent away from the wrong tool.

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

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

With annotations only saying readOnlyHint=false, the description carries the behavioral burden and does it thoroughly: dangling ids are REFUSED, status is computed rather than asserted, statuses are listed, refuted outranks blocked, and return fields are described. This goes well beyond the annotation data.

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

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

The description is organized with clear WHEN/RETURNS/GOTCHAS sections, front-loads the core purpose, and every sentence carries operational value. It is longer than average, but the tool's dual read/write behavior and cross-tool id semantics justify the length.

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

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

Even without an output schema, the description states the return shape ({case_id, added, hypotheses, note}) and explains each status. It also covers edge behavior like dangling references and status precedence, so an agent has everything needed to call the tool correctly and interpret its results.

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

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 both parameters well. The description reinforces the statement param's dual mode and adds the useful note that status has no parameter, but most of this is already present in the schema, so the description adds only moderate extra meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb-plus-resource: either register a candidate explanation or read the ledger. It clearly frames the dual read/write behavior and names the dependent tools (case_record_gap, case_submit_evidence) that consume hypothesis ids, making it easy to distinguish from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It gives an explicit WHEN ('as soon as you have a theory worth testing, and again to see where each one stands') and exact mode-switching guidance: pass statement to add, omit to read. This leaves an agent with no ambiguity about when and how to invoke the tool.

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

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

Beyond the readOnly/idempotent annotations, the description exposes subtle behavior: matching is by version applicability, never similarity; an entry without applies_to can support but never Confirm; and unanswered constraints are not matches ('silence is not a pass'). These gotchas materially change how an agent should interpret results.

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

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

The description is organized with [READ], WHEN, RETURNS, and GOTCHAS sections, front-loads the most important facts, and each sentence contributes either usage context, return shape, or an operational caveat. It is dense but not padded.

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

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 return fields, format categories, conversion needs, and caveats about decisiveness. It also explains the optional case_id behavior and when the extra fields appear, making the tool safe to call correctly.

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

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

The schema already documents case_id at 100% coverage, but the description reinforces the effect of passing it and adds the decisive-here criteria and no-silence rule. This adds practical meaning beyond the schema's version-check wording.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the tool as the read-only view of the knowledge layer: 'What the knowledge layer accepts, and what is mounted.' It distinguishes case_knowledge from case tools like case_get or case_hypotheses by focusing on knowledge formats, mounting, and applicability rather than incident or case state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It gives an explicit WHEN: use it when someone asks what can be added to strengthen conclusions, when explaining why a case cannot reach Confirmed, or when mounting a knowledge library. It does not explicitly name sibling tools as alternatives or state when not to use it, so it falls 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.

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses meaningful behavior: the envelope structure, pagination behavior (no offset, total reports every case, truncated implies older cases need larger limit), and the damaged-folder behavior where cases appear with state='unreadable' rather than disappearing. This is rich, non-obvious context.

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

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

The description is compact and well-structured: a [READ] flag, a one-line purpose, a 'WHEN' usage hint, and a concise return-shape summary. Every sentence contributes meaningful information with no wasted words.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the return envelope, item fields, ordering, pagination, and edge-case behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the limit parameter is already fully documented including default, ordering, and offset behavior. The description adds no new parameter-specific meaning beyond what the schema already states, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a specific verb ('List') and resource ('investigation cases') with an explicit ordering ('newest first'). It is clearly distinguishable from siblings like case_get and case_open, which operate on individual cases rather than listing them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Provides an explicit 'WHEN' clause: use this tool to find the id of a case opened earlier. It does not name sibling alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

The description discloses key behavioral traits: it is a write operation ([WRITE]), it returns a specific set of fields including a 'ceiling' that the agent is told to read, and it has explicit side-effect constraints in GOTCHAS: writes only under $OPS_HOME, never to a VMware system, and never over an existing case. Annotations confirm it is not read-only, not idempotent, and not destructive, and the description adds context beyond these flags (the write location and overwrite prohibition). 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.

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

The description is tightly organized into labeled sections (WRITE, WHEN, RETURNS, GOTCHAS). Each sentence earns its place: it covers purpose, usage, return shape, and side-effects in under 100 words. It front-loads the verb and resource, making it scannable for an agent. No redundancy or filler.

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

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

Given the tool's complexity (6 parameters, all documented in schema, no output schema) the description provides all necessary context: when to use it, what it returns, and critical side-effect constraints. The mention of 'ceiling' and the instruction to read it now prepares the agent for a key return value. The description is sufficient for correct invocation without requiring the agent to infer missing details.

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

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

The input schema has 100% description coverage, with each parameter providing meaningful semantics (e.g., summary is used by case_plan to infer symptom category, window_start warns against invented windows, determined_by explains why it is required). The tool description itself does not add any parameter-specific meaning, but the schema already does. According to the rubric, with high coverage the baseline is 3, and that is appropriate here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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.' It clearly states the action (open) and the resource (investigation case), and provides immediate differentiation from sibling incident_timeline by specifying it is for incidents to reason about rather than glance at. This is a specific, non-tautological statement of purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description contains an explicit 'WHEN:' section: 'at the start of an incident you expect to reason about rather than glance at. For a one-off lookup use incident_timeline alone.' It tells the agent exactly when to use this tool versus an alternative and sets expectations for the place in the workflow (step 01). This is clear, actionable guidance.

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

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

Even with strong annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral detail: recomputation, routing around lost sources, the meaning of unavailable, and the guarantee that empty steps is never silent. This exceeds what annotations alone convey.

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

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

The structured sections (WHEN, RETURNS, GOTCHAS) front-load the purpose and every sentence adds operational value. Despite length, it is tightly organized with no filler.

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

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

For a plan-generating tool with no output schema, the description fully specifies the return fields, per-step shape, how to proceed, and edge cases. An agent has enough to select and invoke the tool correctly.

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

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 case_id, category, max_steps, and available_skills in detail. The description reinforces workflow context but adds no new parameter-level semantics, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'What to fetch next for this case — step 02, recomputed each call,' stating a specific verb and resource. This clearly identifies it as a plan-generation tool, distinct from siblings like case_get or case_timeline which retrieve existing state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

WHEN explicitly says to call right after case_open and after each evidence round, and describes how the plan updates after submissions. It stops short of naming alternative tools or explicit exclusion cases, but the usage context is unambiguous.

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

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

The description goes well beyond the annotations by detailing the return object fields, the unrecognised_skills behavior, the deliberately absent single score, the same-skill-counts-as-one-source gotcha, and the hardware/knowledge class conditions. It also explains why the behavior exists (typo would otherwise read as 'not installed'), which is genuinely useful context.

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

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

The description is well-structured with [READ], WHEN, RETURNS, and GOTCHAS sections, front-loading the purpose and usage before the detailed behavior. The length is justified by the absence of an output schema and the complexity of the edge cases, and every section earns its place.

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

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

With no output schema, the description carries the full burden of explaining return values and edge cases, and it does so thoroughly: object shape, per-class availability, per-category ceilings and independent sources, plus the critical gotchas. For a read-only analysis tool with one optional parameter, nothing an agent needs to call it correctly is missing.

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

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

The schema already fully describes the single optional parameter at 100% coverage, so the baseline is 3. The description adds value by explaining that unmatched names surface in `unrecognised_skills` rather than being treated as 'not installed', and by clarifying that omission reports the family-intrinsic ceiling. This is meaningful extra semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with [READ] and frames the tool as assessing 'what strength of conclusion can this environment reach', which is a clear, specific purpose. It identifies the invocation context ('before starting an investigation') and the scope of the output, distinguishing it from the case_* siblings without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

An explicit WHEN block gives two concrete triggers: before starting an investigation, or when a case will not go higher and the agent wants to know if that is fixable. It does not explicitly name alternatives among the sibling tools, but the timing and purpose are clear enough to prevent obvious misuse.

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

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

Beyond the annotations' bare flags, the description discloses the write nature with '[WRITE]', the return shape {case_id, gap_id, grade, reasons}, and a key side-effect nuance: a recorded gap caps the grade but does not demote it. This meaningfully helps the agent predict consequences beyond what annotations alone provide. No contradiction with the annotations exists.

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

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

The description is tightly organized with WHEN, RETURNS, and GOTCHAS sections, front-loading the core action and keeping every line purposeful. It is concise without losing essential behavioral nuance.

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

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

For a mutating tool with no output schema, the description supplies the return fields and the critical grade-cap behavior. Combined with the fully documented input schema, an agent has everything needed to invoke the tool correctly and understand its consequences.

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

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

Schema description coverage is 100% and each parameter already has rich semantic text, so the baseline is 3. The description adds little parameter-level meaning beyond the schema; its RETURNS line helps with output understanding but not with parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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.' This clearly distinguishes it from sibling tools like case_submit_evidence, which record evidence the case does have, and case_grade, which grades the case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicit when-to-use guidance is provided: 'any time a fetch failed, was refused, returned nothing, or the data simply does not exist in this environment.' It does not explicitly name alternatives or when-not-to-use cases, but the context is clear enough to route an agent correctly.

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

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

Annotations already indicate this is not read-only, and the description adds [WRITE] plus meaningful context: it returns the resulting grade, shows what the payload was read as, and explains that a summary submitted in place of a result will be visible rather than appearing as a zero later. This goes beyond the annotation flags in a useful way.

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

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

The description is tightly structured with labeled sections: [WRITE], WHEN, RETURNS, GOTCHAS. It is front-loaded with the core purpose and every sentence adds either usage guidance, return semantics, or an exclusion rule. No filler.

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

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

Despite having 13 parameters and no output schema, the description covers the essential operational context: when to call it, what it returns, how the payload is interpreted, and where failures belong. Combined with the fully described schema, an agent has enough to invoke this tool correctly.

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

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 itself does not add much parameter-level detail beyond what the schema already provides, though it does contextualize the summary field's role in the return behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Record one retrieved fact — steps 02/03 of the evidence loop.' It also distinguishes itself from the sibling case_record_gap in the GOTCHAS section, so an agent can tell this is for successful evidence, not failed or empty fetches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It explicitly says WHEN to use it: 'after every read-tool call you intend to reason from.' It also gives an exclusion rule: a fetch that failed or came back empty goes to case_record_gap, not here. This is clear routing guidance with a named alternative.

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

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

Annotations are all false, so the description carries the full behavioral burden. It discloses it writes timeline.md (consistent with readOnlyHint=false), explains the tool's reproducibility from the case folder alone, and details the `note` and `rejected` fields, including the three zero-event states and consequences of silent row drops. No annotation contradiction.

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

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

Organized into clear sections (WHEN, RETURNS, GOTCHAS) with the core purpose front-loaded. Every sentence carries weight—no fluff—and the length is justified by the density of critical operational details.

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

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

For a correlation tool without an output schema, the description lists all return fields and explains nuanced behaviors (note, rejected, spike thresholds). It covers usage prerequisites, input expectations, and gotchas, making it self-sufficient for an agent to call accurately.

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

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 meaningful context for `case_id` (source from case_open/case_list, contrast with incident_timeline) and clarifies expected payload format for events (though that's more usage than parameter-specific). Modest value over schema, but not extensive, warranting a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with '[WRITE] Correlate everything this case has collected — steps 04/05,' stating a specific verb, resource, and workflow step. It clearly distinguishes itself from incident_timeline by emphasizing it takes no events and reads submitted payloads, leaving no ambiguity about its role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicit WHEN guidance ('once evidence is in') and a direct contrast with incident_timeline ('Unlike incident_timeline, this takes no events'). It also gives actionable instructions on how to feed the tool ('Submit a read tool's raw result as `payload`') and cautions against using summaries (which carry no rows), fully covering when and how to use it vs alternatives.

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

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

Annotations already declare readOnly/idempotent/destructive-safe, but the description adds concrete behavioral context beyond them: stateless, no network, nothing executed, malformed events return {error, hint} with the offending index. This is substantial added value rather than a restatement of annotations.

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

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

Although long, the description is organized into labeled sections (WHEN, RETURNS, GOTCHAS) with the core purpose front-loaded. Every sentence adds operational information; there is no filler or repetition of schema fields.

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

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 fully covers return shape, binned resolution semantics, ranking interpretation, error behavior, and onward routing. Nothing an agent needs to call this tool correctly and interpret results is missing.

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

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

Schema coverage is 100%, but the description enriches parameters meaningfully: event normalization rules, required event_type retention, bin selection ladder, and the z_threshold flat-series caveat ('empty spikes is not calm'). These details materially change how an agent should populate and interpret parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 differentiates itself from fetching tools by stating it does NOT fetch anything itself, and orients the agent toward sibling list_symptom_categories for prior steps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

A dedicated WHEN section explicitly says to use this after pulling events from named data-source skills, and tells the agent what to do when unsure which events to pull (run list_symptom_categories first). It also routes remediation to specific siblings, leaving no ambiguity about alternatives.

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

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

Annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds valuable context beyond that: 'Read-only; no network access' and explains that the routing table is a fixed constant, so truncated is always false and total exact. This tells the agent the result is deterministic and complete, not paginated—exactly what it needs to trust the output.

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

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

The description is a single dense paragraph but front-loaded with the core purpose, then usage, then return format. Each sentence earns its place—there's no fluff. It's slightly longer than the minimum but the length is justified by the need to explain the deterministic nature and the follow-up step. Structure is logical and easily parsed.

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

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

For a simple tool with no parameters and no output schema, the description covers all necessary context: the purpose, the usage trigger, the exact return envelope with field names, and the note about total exactness. It even explains how to use the output (pass events to incident_timeline). An agent would have everything needed to call this tool correctly and interpret its result.

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

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

The tool has zero parameters, and the description explicitly states 'Takes no parameters,' which matches the schema. Since there is nothing to elaborate, the description fully covers the parameter surface. No additional meaning is needed, and the description goes beyond by explaining the return envelope, though that's more behavioral than parameter-specific.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the specific action (List) and resource (symptom categories) and elaborates on content: example keywords and a suggested next check. It clearly differentiates this from sibling incident_timeline by framing it as the initial triage step, so an agent can distinguish it without opening other schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Provides an explicit trigger: 'Use this when you don't yet know what to look at.' It also gives a concrete follow-up flow—'gather the events those checks name and pass them to incident_timeline'—which tells the agent exactly when to use this tool and how it feeds into the broader investigation workflow.

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