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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, but the description adds context beyond them: stateless, no network, nothing executed, remediation routed to vmware-aiops or vmware-pilot, and explicit failure behavior ({error, hint} naming the offending index rather than skipping). That is substantive behavioral disclosure.

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?

Labeled WHEN/RETURNS/GOTCHAS sections front-load the routing decision before the return shape, and each line carries information. The RETURNS block is long, but with no output schema it is doing necessary work rather than padding.

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?

No output schema exists, so the description carries the full return contract (event_count, binning, classification, spikes/spikes_total, hypotheses with suggested_check, next_checks) plus error shape and follow-on routing. Nothing an agent needs to call or interpret this tool 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 schema already documents ts formats, severity normalization, binning ladder and z_threshold caveats, so the baseline is 3. The description mostly reiterates this; its only added guidance (keep event_type in fields) duplicates the schema text rather than extending it.

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?

States a specific verb and resource ('Correlate already-fetched VMware events into one incident view') and draws a hard boundary that separates it from the data-source siblings: 'This tool does NOT fetch anything itself.' An agent can distinguish this from get_events/list_alerts without opening a schema.

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 block names the upstream skills whose output feeds this tool, gives an explicit prerequisite (list_symptom_categories first when unsure what to pull), and states the exclusion ('does NOT fetch'). Use-vs-alternative routing is fully specified.

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 only give the bare safety profile (write, not read-only, not idempotent, not destructive). The description adds real context: an already-closed case is refused, the record is never rewritten, and open_gaps is surfaced at closing time. The 'not closed again / never rewritten' behavior is consistent with idempotentHint=false.

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?

Front-loaded with a [WRITE] marker and one-line purpose, then cleanly sectioned into WHEN / RETURNS / GOTCHAS. Every sentence carries information an agent needs and none is redundant.

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 helpfully enumerates the return shape ({case_id, state, grade, open_gaps, path, note}), plus trigger conditions and irreversible-behavior caveats. Nothing needed to call this 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 coverage is 100% and the single case_id parameter is already well documented in the schema, including the note that there is no grade parameter. The description restates the grade-computation behavior but adds no syntax or format detail 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.

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

The description gives a specific verb (archive/record grade), the resource (the case), and its position in the workflow (step 08). It clearly separates this from siblings like open_case and grade_case by stating that closing computes the grade rather than accepting one.

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 line names the trigger (investigation finished or being handed over), and the GOTCHAS section explicitly routes the reopen scenario to opening a new case that cites this one. It also explains why closing is one-way, so the agent won't reach for a reopen tool that doesn't exist.

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/non-destructive, so the bar is lower. The description adds real behavioral value: it returns counts and identifiers rather than whole evidence bodies, and flags that an unknown id is an error rather than an empty case.

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?

Front-loaded with the core statement, then clearly sectioned into WHEN and RETURNS. Every sentence carries information, and the return-field enumeration compensates for the absent output schema.

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 takes on the burden of documenting the return shape and does so explicitly, including the subtle meaning of 'sources'. Nothing an agent needs to call this 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?

With a single parameter at 100% schema coverage, the schema fully documents case_id (including its error behavior). The description adds no syntax or format detail beyond that, 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?

States a specific operation ('One case') plus what it exposes (scope, ledger sizes, grade history), and the '[READ]' tag and singular scope distinguish it from siblings like list_cases and open_case. An agent can tell what this returns without consulting the schema.

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 concrete triggers ('pick up an investigation', 'see why a case sits at the grade it does') and steers away from using it for full evidence, pointing to the case folder via open_case's path. It does not explicitly compare against get_case_readiness or get_case_knowledge, so it stops short of full alternative routing.

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/non-destructive, so the safety profile is covered. The description goes further with real behavioral disclosure: version-checking only happens when case_id is passed, and the GOTCHAS explain that decisive matching is by version applicability, not similarity, and that silence is not a pass. That is meaningful context beyond structured fields.

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?

Front-loads the one-line purpose then uses WHEN/RETURNS/GOTCHAS headings, which scan well. It is on the verbose side (long GOTCHAS prose), but each section carries distinct information rather than padding.

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 takes on return-value explanation and does so thoroughly: it enumerates the return keys, describes what `formats` and `needs_conversion` contain, and pre-empts the most likely misreading (showing how entries qualify as decisive). An agent has everything needed to call and interpret it.

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 case_id description already explains omission vs. passing a case id and the resulting `applicable`/`decisive_here` fields. The prose only restates that behavior, adding no syntax or format detail the schema lacks; 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?

States a concrete verb+resource: 'What the knowledge layer accepts, and what is mounted.' An agent can distinguish this from siblings like get_case_readiness or get_case, though the terms 'knowledge layer' and 'mounted' are domain jargon that isn't defined inline.

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 block gives explicit triggering conditions ('when someone asks what can be added to make conclusions stronger', 'when a case will not reach Confirmed'). It does not name competing siblings (e.g. get_case_readiness) or state when NOT to use it, so it stops short of a 5.

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 cover the safety profile (readOnly, idempotent, not destructive, closed-world), and the description adds genuinely non-obvious behavior: two classes served by the same skill count as one source, the hardware class is never reachable in this family, and the knowledge class only activates with entries under $OPS_HOME/knowledge/. These are real traps an agent could not derive from structured fields.

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?

Front-loaded with a [READ] tag and WHEN/RETURNS/GOTCHAS sections, which makes scanning easy. There is mild redundancy: unrecognised_skills behavior is explained in both the RETURNS block and the parameter schema, and the category enumeration is lengthy, but the structure earns its length for a no-output-schema tool.

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 must carry the return contract, and it does: field names, the rationale for unstructured ceilings over a single score, and an explicit statement that no aggregate score exists. Combined with the gotchas, an agent has everything needed to call and interpret this 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 single optional parameter's aliasing rule ('monitor' vs 'vmware-monitor') and omit-behavior are already documented in the schema. The description restates the unrecognised_skills consequence rather than adding new semantics. 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 specific, if rhetorically framed, purpose: determining what strength of conclusion the environment can reach. The RETURNS block makes the resource concrete (evidence classes, symptom categories, ceilings). It stops short of naming siblings like grade_case or plan_case, so an agent must infer the boundary between 'readiness' and 'grading' from context.

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 clause gives two triggering conditions: before starting an investigation, and when a case stalls and you want to know if the ceiling is fixable. It even argues the sequencing ('worth far more than discovering it halfway through'). No explicit when-not or named alternative tool, which keeps it from a 5.

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 mark this as a non-idempotent write (readOnlyHint=false, idempotentHint=false), and the description adds substantive context beyond them: the grade is recomputed from the ledger on every call, every grading is appended to conclusion.md and never rewritten, and the stock-install ceiling limits results to 'probable'. The 'no grade parameter' design constraint is exactly the kind of non-obvious behavior an agent must know 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.

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

Front-loaded with purpose and a WHEN block, then labeled RETURNS and GOTCHAS sections — an agent can skim to what it needs. It is long, and the level definitions are dense, but the length is load-bearing because there is no output schema to carry that semantics; a little of the level prose could still be tightened.

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?

This is a complex, logic-heavy grading tool with no output schema, and the description compensates by enumerating the return keys, explaining direction/ceiling semantics, and defining each grade level with its evidence requirements. Nothing an agent needs to invoke it correctly or interpret its result 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% for the single case_id parameter, so the baseline is 3. The description goes further by explaining why no grade parameter exists and why passing one is impossible, and by pointing to open_case/list_cases as the source of the id — meaning that adds value beyond the schema field text.

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?

States a specific verb and resource — '[WRITE] Compute and record the conclusion grade' — with the pipeline position (steps 07/08). It is immediately distinguishable from siblings like get_case_readiness (a read of readiness) and close_case (termination), so an agent knows this is the tool that writes the grade.

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 block gives explicit conditions to call it ('when you think the investigation has reached a conclusion, or to record where it stands before handing it over'). It also routes the agent away from the wrong corrective action: if you disagree with the computed grade, submit evidence or record the gap rather than trying to assert a level.

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/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond annotations: the return envelope shape {items, returned, limit, total, truncated, hint}, and the notable edge case that damaged cases appear with state='unreadable' rather than disappearing.

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?

Front-loads the [READ] tag and purpose, then WHEN, then return shape. Slightly dense in the middle paragraph but every sentence carries information; 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?

Covers purpose, when-to-use, return envelope, and an important edge case, which is strong for a listing tool with no output schema and rich annotations. Could be 5 with explicit sibling routing, but it's complete enough 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?

Schema coverage is 100%, so the single 'limit' parameter is already fully documented in the schema (default 50, no offset, truncated behavior). The description adds nothing parameter-specific beyond what the schema says. 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?

States a clear verb+resource ('List investigation cases') with ordering ('newest first'). It is distinguishable from get_case/open_case by being a listing operation, but it doesn't explicitly name how it differs from siblings beyond the WHEN line.

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 line explicitly frames the use case: 'to find the id of a case you or someone else opened earlier.' This tells the agent the discovery intent that routes here rather than to get_case (which needs an id). No explicit exclusions, but the context is clear.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false). The description adds non-obvious behavioral facts: it takes no parameters, the table is a fixed constant so truncated is always false and total is exact, and there is no network access. It stops short of anything beyond that, but this is solid added context over 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?

Front-loaded with the [READ] marker and the core purpose, then the when-to-use and the return-envelope details. Every clause earns its place, though the return-envelope enumeration is slightly dense and could be trimmed.

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 and no parameters, the description carries the full burden and does so: it spells out the envelope shape {items, returned, limit, total, truncated, hint} and each item's fields, plus the completeness guarantee. An agent has everything needed to call and consume it.

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?

Zero parameters, so the baseline is 4. The description explicitly confirms "Takes no parameters," which is consistent with the empty schema and removes any doubt about required inputs.

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?

States a specific verb+resource -- lists the symptom categories the tool recognizes -- and enumerates what each item contains (example keywords, suggested next check). It is clearly distinguishable from the case-management siblings and the timeline builder it routes to.

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?

Explicitly names the trigger condition ("Use this when you don't yet know what to look at") and the follow-on workflow (gather the named events, then pass them to build_incident_timeline). The routing to a specific sibling tool leaves nothing to inference.

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=false and idempotentHint=false; the description goes further with GOTCHAS that the annotations cannot express: writes are confined to $OPS_HOME, never touch a VMware system, and never overwrite an existing case. It also tells the agent to read `ceiling` immediately and explains what that field means, which is real behavioral guidance.

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?

Front-loaded with a [WRITE] tag and purpose, then cleanly segmented into WHEN / RETURNS / GOTCHAS blocks. Every sentence carries load; 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 6-parameter write tool with no output schema, the description compensates by enumerating the return keys and flagging the one the agent must read. Combined with write-scope caveats and the routing to build_incident_timeline, nothing an agent needs to invoke it correctly is absent.

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 every parameter (summary, window_start/end, determined_by, objects, product_versions) is already explained with rationale in the schema itself. The description adds no additional parameter-level meaning, 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 gives a specific verb+resource ('Open an investigation case') and positions it as 'step 01, define the event' in a named workflow. It explicitly contrasts with the sibling build_incident_timeline for one-off lookups, so an agent can distinguish it without opening 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?

The WHEN block states the trigger ('at the start of an incident you expect to reason about rather than glance at') and names the alternative tool plus the condition that selects it ('For a one-off lookup use build_incident_timeline alone'). No inference required.

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 establish read-only/idempotent/closed-world, and the description still adds substantial behavior: outputs are recomputed per call, `unavailable` sources carry how_to_supply rather than being dropped, empty `steps` is never silent (a `note` explains why), and `category_signals` should be inspected first. These are real operational traits not derivable from 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 WHEN/RETURNS/GOTCHAS structure front-loads the essentials and the return-shape block is dense but information-bearing. It runs long and leans on prose-heavy gotchas, but almost every sentence carries distinct guidance rather than padding.

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?

There is no output schema, so the description must describe the return contract itself, and it does: the top-level keys, the per-step shape {evidence_class, skill, tool, purpose, objects, window, degraded}, and edge-case semantics. For a 4-parameter planning tool, an agent has everything needed to call and interpret 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?

Schema coverage is already 100%, so 3 is the floor; the description goes beyond it by explaining the rationale for max_steps' default (6 = two rounds across three classes, and two independent sources to reach Probable), the below-1 refusal behavior, and how category inference ties to category_signals. It clarifies the consequence of parameters rather than restating them.

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?

Opens with a specific verb+resource: '[READ] What to fetch next for this case — step 02, recomputed each call.' The scope (next-fetch planning for a case) and its read-only nature are unambiguous, and it is clearly separable from siblings like submit_case_evidence, grade_case, and open_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?

The WHEN block gives explicit timing: 'right after open_case, and again after each round of evidence.' It also states the interactive contract with a named sibling ('call that skill's tool, then submit the result with submit_case_evidence') and clarifies it is not a checklist, so the agent knows both when and how to re-invoke it.

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 this is a write (readOnlyHint=false) that is non-idempotent and non-destructive; the description adds genuinely new behavior beyond them — recording a gap caps a grade rather than demoting it, and is intended to be 'free,' which tells the agent there is no penalty cost to logging gaps. It does not address duplicate/non-idempotent writes, which is the only notable omission.

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?

Sectioned as WHEN / RETURNS / GOTCHAS with the write marker and core definition front-loaded. Every sentence carries information an agent needs, with no restatement of the schema or name.

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 six-parameter write tool with no output schema, the description supplies the return shape ({case_id, gap_id, grade, reasons}), the trigger conditions, and the consequence semantics. Nothing required to call it correctly — case_id provenance, gap semantics, grade impact — 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%, so all six parameters, including the subtle could_falsify and how_to_close semantics, are already documented in the schema. The description's only parameter-adjacent content is the RETURNS shape, not the inputs, 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?

The description states a specific verb+resource ('Record something the investigation could NOT obtain') and immediately demarcates it from the evidence-writing siblings by defining a gap as an unobtainable observation. An agent can distinguish this from submit_case_evidence or record_case_hypothesis without opening any schema.

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 concrete triggers (fetch failed, refused, returned nothing, data does not exist in this environment) plus a rationale for why recording matters. It stops short of naming a sibling tool as the alternative for the opposite case (e.g., 'if you did obtain it, use submit_case_evidence'), so it is clear context without explicit routing.

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 only give the generic profile (not read-only, not idempotent, not destructive); the description adds the real behavioral contract: omitting `statement` is a pure read, ids are auto-assigned (H1, H2, …), unregistered ids are REFUSED rather than ignored, and status is computed rather than asserted. The GOTCHAS precedence rule ("refuted outranks blocked") is exactly the kind of non-obvious trait annotations cannot express.

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?

Front-loaded with a bracketed [WRITE] tag and labeled WHEN / RETURNS / GOTCHAS blocks that make scanning easy. It is longer than most, and a few clauses ("which quietly reports a stronger case than you have") lean rhetorical, but each block carries distinct information.

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?

There is no output schema, so the description supplies the return shape ({case_id, added, hypotheses, note}), the status vocabulary (refuted/blocked/open), the `refuted_by` field, and the resulting next step. For a two-parameter ledger tool in an evidence-grading workflow, nothing needed 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?

Schema coverage is already 100%, so the baseline is 3, but the description earns more by explaining the id-assignment scheme for `statement` and the deliberate absence of a status parameter ("status is computed from the evidence and gaps that point at it"). It adds semantics the schema cannot: that omitting statement must not be treated as an empty write.

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?

"[WRITE] Register a candidate explanation" gives a specific verb and resource, and the description immediately disambiguates the dual mode: with `statement` it adds a hypothesis, without it only reads the ledger. This distinguishes it from siblings like record_case_gap and submit_case_evidence, which are named as downstream consumers of the ids this tool mints.

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 clause states the trigger ("as soon as you have a theory worth testing") and the re-use case ("again to see where each one stands"). It also explicitly routes cross-tool usage by naming record_case_gap(blocks=[...]), submit_case_evidence(falsifies=[...]) and grade_case as the things that give a hypothesis its status.

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 only declare the write/non-destructive profile; the description goes well beyond by disclosing that timeline.md is written, that the result is reproducible from the case folder, that unreadable rows are surfaced via `rejected` rather than silently dropped, and that `note` disambiguates three zero-event states. This is exactly the behavioral context annotations cannot carry.

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?

Front-loaded with a bracketed operation tag and organized under WHEN/RETURNS/GOTCHAS headers, so an agent can scan it quickly. The GOTCHAS paragraph is dense and slightly long, but each sentence carries a distinct operational fact.

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 enumerates the return keys and explains the two most easily misread ones (`note`, `rejected`), plus the side effect of writing timeline.md. For a four-parameter write tool this covers everything needed to invoke and interpret it.

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 top_n, bin_seconds, and z_threshold are already fully documented in the schema, and the description does not restate them. It adds only indirect parameter context via the payload-submission prerequisite and the return-key list. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a specific verb (correlate) and resource (everything the case has collected), and explicitly contrasts itself with build_incident_timeline, noting it takes no events. An agent can distinguish it from its siblings without opening the schema.

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

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

Gives an explicit trigger ("WHEN: once evidence is in") and names the alternative (build_incident_timeline) along with the distinguishing condition (takes no events). The GOTCHAS section also tells the agent the prerequisite that a read tool's raw result must have been submitted as `payload`.

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 cover the safety profile (readOnlyHint=false, idempotentHint=false), so the bar is lower, but the description still adds real value: it discloses the return shape ({case_id, evidence_id, payload_events, payload_note, grade, reasons}), why grade is returned (no second call needed), and the cross-tool consequence that a summary submitted in place of a raw payload becomes visible here rather than as a later zero. It does not itself warn about duplicate submissions, relying on the idempotency annotation for that.

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?

Front-loaded with the [WRITE] marker, then split into labeled WHEN / RETURNS / GOTCHAS sections. Every sentence carries operational content; nothing is padding.

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 13 parameters at 100% schema coverage and no output schema, the description carries the return-shape burden itself and does so. The routing rule to record_case_gap and the grade-return rationale close the loops an agent needs before calling.

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, but the description adds cross-parameter meaning beyond the per-field docs: it explains that the payload is read as raw events and that a summary used in its place is detectable via payload_note. The payload/summary/grade interplay is genuinely useful framing the schema does not state.

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?

States a specific verb+resource ("Record one retrieved fact") and frames it in the case workflow ("steps 02/03 of the evidence loop"). The GOTCHAS section explicitly names the sibling it is NOT (record_case_gap), so an agent can separate them without opening either schema.

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?

Gives an explicit trigger ("after every read-tool call you intend to reason from") and an explicit exclusion with the alternative ("a fetch that failed or came back empty goes to record_case_gap, not here"). Both the when and the when-not are stated, not inferred.

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