Provides diagnostic tools for VMware environments, correlating events and ranking hypotheses from logs and symptoms.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.github.zw008/vmware-debug Show timeline for recent ESXi host failures"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⚠️ Work in progress — the core (event correlation engine, MCP tools, CLI) is built and tested; README,
server.json, full reference docs, and packaging polish are still landing. Not yet published to PyPI.
Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc. "VMware" and "vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT license.
The diagnostic brain of the VMware skill family. You bring the symptom (an error,
a log dump, a slow VM); this skill runs a systematic investigation, correlates
events from the other skills into one timeline, ranks root-cause hypotheses, and
tells you what to check next. It is read-only — it never changes anything and
never executes fixes. Remediation is routed to vmware-aiops (single op) or
vmware-pilot (multi-step, gated), mirroring the vmware-harden → vmware-pilot
advisor/executor split.
See skills/vmware-debug/SKILL.md for the full
methodology, the event-envelope contract, and symptom routing.
Tool | What |
| [READ] Correlate pre-fetched events → timeline + spikes + ranked hypotheses + next-check ideas |
| [READ] List recognised symptom categories + what to check for each |
Related MCP server: vcf-mcp-sddc-vc
This project uses the modern PEP 517 build system (hatchling), so there is no
setup.py by design — that is expected, not a missing file. If you cloned the
source and hit ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build, your pip is older than 21.3 and
cannot do an editable (-e) install with a non-setuptools backend. Editable
mode is a developer convenience, not needed to run the tool — do one of:
# From the source tree — a normal (non-editable) install builds a wheel:
pip install . # NOT pip install -e .
# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .For a truly air-gapped host, build the wheels on a connected machine and copy them over — the target then needs no network:
# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist # → dist/*.whl (or: uv build, for just this package)
# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-debugMIT.
[WRITE] Record the final grade and archive the case — step 08.
WHEN: when the investigation is finished, or is being handed over. Closing turns a working folder into a record other people rely on, so it computes and records the grade rather than accepting one.
RETURNS: {case_id, state, grade, open_gaps, path, note}. open_gaps
names anything still blocking a hypothesis at the moment of closing —
stated here rather than left in the file for someone to find.
GOTCHAS: a closed case is not closed again and its record is never rewritten. To reopen the question, open a new case that cites this one, so the original conclusion and whatever changed it both stay readable.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes | The case to close (from case_open/case_list). There is no grade parameter — closing recomputes the grade from the ledger. An already-closed case is refused rather than closed again. |
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.
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.
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.
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.
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.
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.
[READ] One case: its scope, its ledger sizes, and its grade history.
WHEN: to pick up an investigation, or to see why a case sits at the
grade it does. Returns counts and identifiers rather than the whole
ledger — read the case folder itself (the path from case_open) for
full evidence bodies.
RETURNS: {case_id, path, state, grade, opened_at, scope, evidence_count,
sources, gap_count, blocking_gaps, grade_history}. sources is the
distinct skills evidence came from, which is what corroboration is
counted in.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes | The case id returned by case_open, or listed by case_list. An unknown id is an error, never an empty case. |
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.
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.
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.
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.
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.
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.
[WRITE] Compute and record the conclusion grade — steps 07/08.
WHEN: when you think the investigation has reached a conclusion, or to record where it stands before handing it over.
There is deliberately NO parameter for the grade. You cannot state a conclusion level; it is recomputed from the ledger on every call. If you disagree with the result, change the ledger — submit the evidence that is missing, or record the gap that is blocking it.
The levels: Candidate (a hypothesis exists); Probable (at least two INDEPENDENT sources agree — two calls to the same skill are one source — and nothing outstanding could overturn it); Confirmed (that, plus a decisive item: a direct hardware diagnostic, a version-checked knowledge-base entry, or a vendor SR, and no gap left open); Excluded (an observation that actually rules the hypothesis out — "we looked and found nothing" is a gap, not an exclusion).
RETURNS: {grade, previous, direction, reasons, ceiling, ceiling_reasons,
rules_source, rules_origin}. direction is initial/up/down/unchanged —
grades may go DOWN, and the history records it when they do.
GOTCHAS: on a stock install ceiling is "probable", because Confirmed
needs a decisive source and there is neither a hardware-diagnostic
channel nor a knowledge library mounted yet. That is a real limit, not
a caution. Every grading is appended to conclusion.md and none is ever
rewritten.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes | The case to grade (from case_open/case_list). This is the only parameter — see above for why there is no grade parameter. |
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.
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.
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.
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.
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.
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.
[WRITE] Register a candidate explanation, or read the ledger — step 06.
WHEN: as soon as you have a theory worth testing, and again to see where
each one stands. Pass statement to add one; omit it to just read.
Every hypothesis gets an id (H1, H2, …). Those ids are what case_record_gap(blocks=[...]) and case_submit_evidence(falsifies=[...]) refer to, and an id that was never registered is REFUSED rather than ignored — a dangling reference blocks nothing and falsifies nothing, which quietly reports a stronger case than you have.
RETURNS: {case_id, added, hypotheses, note}. Each entry carries its
status and what produced it: refuted (an observation ruled it out,
with the evidence id), blocked (a gap is in the way, with the gap id
and how to close it), or open. Status is computed from what points at
the hypothesis — a hypothesis does not get to claim it is well
supported, the same way a case does not get to state its own grade.
GOTCHAS: refuted outranks blocked. Once an observation settles the question, a missing measurement no longer matters.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes | The case whose hypothesis ledger this is (from case_open/case_list). | |
| statement | No | The candidate explanation, in one line. Pass it to register a new hypothesis, which is assigned the next id (H1, H2, …); omit it to read the ledger without changing it. There is no parameter for a hypothesis's status — status is computed from the evidence and gaps that point at it. |
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.
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.
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.
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.
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.
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.
[READ] What the knowledge layer accepts, and what is mounted.
WHEN: when someone asks what can be added to make conclusions stronger, or when a case will not reach Confirmed and you need to say why in terms they can act on. This is the answer to "which knowledge formats do you take" — the first question anyone mounting a library asks.
RETURNS: {root, sections, entries, with_applies_to, by_source, unreadable, unsupported, formats, needs_conversion, note} — plus {applicable, decisive_here} when a case_id is given.
formats lists every extension read and how each carries its metadata:
Markdown front-matter, YAML/JSON whole-file, JSONL per line, CSV/TSV per
row, and plain text with a sibling .yaml. needs_conversion names the
ones that must become Markdown first (PDF, DOCX, PPTX, HTML).
GOTCHAS: an entry is decisive ONLY if its applies_to block was checked
against the case scope and passed — matching is by version
applicability, never by similarity, because an entry written for the
wrong build reads exactly like the right one. An entry with no
applies_to can support a hypothesis but can never make a case
Confirmed. A constraint the case scope cannot answer is not a match
either: silence is not a pass.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | No | Omit to describe the knowledge layer itself — what formats are read and what is mounted. Pass a case id and every mounted entry is additionally version-checked against THAT case's product_versions, adding `applicable` and `decisive_here` with the reason each entry did or did not qualify. |
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.
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.
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.
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.
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.
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.
[READ] List investigation cases, newest first.
WHEN: to find the id of a case you or someone else opened earlier. Returns the family list envelope {items, returned, limit, total, truncated, hint}; each item is {case_id, summary, state, grade, opened_at}. A case whose folder is damaged appears with state="unreadable" rather than vanishing from the list.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum cases in the page, newest first (default 50). There is no offset — 'total' reports every case, so when truncated is true the only way to reach older ones is a larger limit. |
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.
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.
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.
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.
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.
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.
[WRITE] Open an investigation case — step 01, define the event.
WHEN: at the start of an incident you expect to reason about rather than glance at. For a one-off lookup use incident_timeline alone.
RETURNS: {case_id, path, state, grade, ceiling, ceiling_reasons, next}.
Read ceiling now — it is the best grade this install can reach at all.
GOTCHAS: writes only under $OPS_HOME, never to a VMware system, and never over an existing case.
| Name | Required | Description | Default |
|---|---|---|---|
| objects | No | Entities in scope, names or MoIDs ("vm-web01", "host-12"). Omit for a case not yet pinned to specific objects. | |
| summary | Yes | What is wrong, one line. case_plan reads it to infer the symptom category, so name the symptom in the estate's own words ("datastore latency on cluster-a"), not a diagnosis. | |
| window_end | No | Believed end, ISO-8601. Omit while still in progress. | |
| window_start | No | When the incident is believed to have started, ISO-8601. Omit if unknown — evidence gets fetched against it, so an invented window is worse than none. | |
| determined_by | Yes | HOW the scope was decided — "user report", "vCenter alarm 42". Required: a scope from a phone call and one from an alarm id support different conclusions, and nobody remembers which it was later. | |
| product_versions | No | Versions keyed by product — {"esxi": "8.0.3"} — plus "driver.<name>" / "firmware.<name>" entries. Knowledge-base entries are version-checked against this: one constraining a product absent here can support a hypothesis but never make the case Confirmed, since an unanswerable constraint is not a pass. |
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.
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.
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.
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.
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.
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.
[READ] What to fetch next for this case — step 02, recomputed each call.
WHEN: right after case_open, and again after each round of evidence. It is not a checklist: submit something and the next plan is shorter, lose a source and it routes around it.
RETURNS: {category, category_signals, steps, already_covered, held_back, unavailable, ceiling, note}. Steps are interleaved across evidence classes, so you get breadth before depth — corroboration is counted in distinct sources, which is what actually moves the grade. Each step is {evidence_class, skill, tool, purpose, objects, window, degraded} — call that skill's tool, then submit the result with case_submit_evidence.
GOTCHAS: unavailable is the important half. A source this install
cannot reach is listed there with how_to_supply rather than left out, so
the gap is visible now instead of when the conclusion refuses to firm
up. An empty steps is never silent — note says whether everything
reachable is already in, or whether nothing here can be reached.
category_signals names the words that chose the category, and any
category that also matched — check it first, since the rest runs off
that one word.
| Name | Required | Description | Default |
|---|---|---|---|
| case_id | Yes | The case to plan for (from case_open/case_list). | |
| category | No | Force the symptom class instead of inferring it. Exactly one of: storage, network, compute, ha_drs, configuration, accelerator, kubernetes, hardware, host_lifecycle, power_lifecycle, auth, platform. Omit to infer, then read `category_signals` for the word that decided it. | |
| max_steps | No | HAS NO EFFECT in this release — accepted but never forwarded to the planner, which always caps at 6. The result's note may still advise raising it; doing so changes nothing. Read `held_back` for how many steps were cut. | |
| available_skills | No | Narrow to the skills actually installed, in either spelling ("monitor" or "vmware-monitor"). Omit to assume all of them, which can produce steps this install cannot run. |
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.
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.
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.
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.
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.
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.
[READ] What strength of conclusion can this environment reach?
WHEN: before starting an investigation, or when a case will not go higher and you want to know whether that is fixable. Answering this first is worth far more than discovering it halfway through.
RETURNS: {classes, categories, unrecognised_skills, note}. A name that
matched no skill in the catalogue comes back in unrecognised_skills
rather than being absorbed into "not installed" — otherwise a typo reads
as advice to install something you already have. Per evidence class:
whether it is
available, through which tools, and if not, how_to_supply. Per
symptom category (storage, network, compute, ha_drs, configuration,
accelerator, kubernetes, hardware): a ceiling and the
independent_sources behind it. There is deliberately no single score —
"readiness 78%" cannot be acted on, "storage reaches Probable, hardware
reaches Candidate" can.
GOTCHAS: two classes served by the SAME skill count as one source, so two available classes do not always mean Probable. The hardware class is unavailable no matter what is installed — nothing in this family reaches below ESXi — and the knowledge class becomes available only when entries are mounted under $OPS_HOME/knowledge/.
| Name | Required | Description | Default |
|---|---|---|---|
| available_skills | No | The skills actually installed and configured, in either of the family's spellings — "monitor" and "vmware-monitor" name the same thing. Omit to assume all of them, which reports the ceiling imposed by the family itself rather than by this install. A name matching no catalogued skill comes back in `unrecognised_skills` rather than being read as "not installed". |
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.
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.
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.
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.
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.
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.
[WRITE] Record something the investigation could NOT obtain.
WHEN: any time a fetch failed, was refused, returned nothing, or the data simply does not exist in this environment. This is the tool that keeps a case honest: an unrecorded gap makes it look better supported than it is.
RETURNS: {case_id, gap_id, grade, reasons}.
GOTCHAS: recording a gap does not punish the case for the evidence it does have — a missing confirmation caps the grade, it does not demote it. Writing gaps down is meant to be free.
| Name | Required | Description | Default |
|---|---|---|---|
| why | Yes | Why it could not be had — refused, unreachable, collected by nothing in this family, absent from this environment. | |
| what | Yes | The observation that could not be obtained — the thing you wanted, not the error you got. | |
| blocks | No | Hypothesis ids (H1, H2, …) this gap holds up; they must already exist via case_hypotheses. Empty is fine. | |
| case_id | Yes | The case this gap belongs to (from case_open/case_list). | |
| how_to_close | Yes | The next action that would close it, even outside this system ("open a vendor SR"). A gap with no stated next action reads like a to-do and gets skipped. | |
| could_falsify | No | Would OBTAINING this be able to prove the hypothesis WRONG? false (default) is the ordinary case — missing corroboration, capping the case below Confirmed. true means it could overturn the hypothesis, holding it at Candidate. |
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.
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.
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.
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.
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.
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.
[WRITE] Record one retrieved fact — steps 02/03 of the evidence loop.
WHEN: after every read-tool call you intend to reason from.
RETURNS: {case_id, evidence_id, payload_events, payload_note, grade, reasons} — the resulting grade, so you need no second call to see whether this changed anything, and what the payload was read as, so a summary submitted in place of a result is visible here rather than as a zero from case_timeline later.
GOTCHAS: a fetch that failed or came back empty goes to case_record_gap, not here.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | The exact parameters the tool was called with, so it can be re-run. Omit only if there genuinely were none. | |
| case_id | Yes | The case this fact belongs to (from case_open/case_list). Required. | |
| payload | No | The read tool's RAW result, not a summary. For its events to reach case_timeline it must be a list of event dicts, or carry them under 'items', 'events' or 'rows'. What was found comes back as payload_events/payload_note. | |
| summary | Yes | What this item shows, one line. | |
| falsifies | No | Hypothesis ids (H1, H2, …) this observation RULES OUT — the only route to Excluded; "we looked and found nothing" is a gap, not an exclusion. Ids must already exist via case_hypotheses; an unregistered id is refused and nothing is written. | |
| fetched_at | No | When the fetch happened, ISO-8601. Omit to stamp now — wrong for an item transcribed from earlier. | |
| window_end | No | End of the period the data covers, ISO-8601. | |
| source_tool | Yes | The tool within that skill, e.g. "get_events". Required, non-blank — "monitor said so" is not reproducible. | |
| time_source | No | Whose clock stamped it — "vcenter", "host" or "client". Recorded so a reader can judge whether two sources' timestamps compare; nothing in this release corrects for it. Null when unknown, never a guess. | |
| clock_skew_s | No | Known offset of that clock from UTC, in seconds. Recorded, likewise not applied. Null when unknown. | |
| source_skill | Yes | The skill that produced it, as the family spells it — "vmware-monitor", "vmware-aria", "vmware-log-insight". Required, non-blank. Two items from the SAME skill count as ONE source when corroboration is counted, so this string decides whether the case can reach Probable. Two reserved values name the knowledge layer instead: "knowledge-kb" and "knowledge-sr", the only sources that can be decisive. | |
| window_start | No | Start of the period the DATA COVERS, ISO-8601 — not when it was fetched. get_events(hours=24) run at 10:00 and at | |
| knowledge_entry_id | No | Which mounted knowledge entry this item IS. REQUIRED when source_skill is knowledge-kb or knowledge-sr — without it the entry's applies_to cannot be checked, so it counts as ordinary support and can never make the case Confirmed. case_knowledge lists what is mounted. |
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.
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.
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.
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.
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.
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.
[WRITE] Correlate everything this case has collected — steps 04/05.
WHEN: once evidence is in. Unlike incident_timeline, this takes no events: it reads the payloads already submitted, so the result is reproducible from the case folder alone months later, on a machine with access to nothing.
RETURNS: {event_count, window, binning, classification, spikes, spikes_total, hypotheses, evidence_without_events, evidence_without_events_detail, rejected, note} and writes timeline.md.
GOTCHAS: note distinguishes three states that all show zero events —
no evidence submitted at all, evidence that carried none, and a genuinely
quiet window — and names which items carried none, with what they held
instead. rejected names any row that could not be read, with the
evidence item it came from; dropping those silently would shrink the
picture the conclusion rests on. Submit a read tool's raw result as
payload for its events to reach here — a summary of the result carries
no rows, and case_submit_evidence says so at the time.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | How many ranked hypotheses come back (default 5). Spikes are capped separately at 20, true count in 'spikes_total'. | |
| case_id | Yes | The case whose submitted payloads are correlated (from case_open/case_list). Unlike incident_timeline this takes no events — everything comes from the case folder. | |
| bin_seconds | No | Time-bin width in seconds. Omit and it is chosen from event density (ladder 1..86400, finest width still averaging 4 events per bin); `binning` reports which was used. | |
| z_threshold | No | Standard deviations above the mean bin count that mark a spike (default 2.0). Under 3 bins, or a flat series, yields none at any threshold. |
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.
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.
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.
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.
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.
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.
[READ] Correlate already-fetched VMware events into one incident view.
WHEN: use this after you've pulled events for an incident from the data-source skills (vmware-monitor get_events/get_alarms, vmware-aria list_alerts/list_anomalies, vmware-log-insight log_search/log_aggregate, vmware-nsx) — feed them here to find what correlates and where to look next. Not sure which events to pull? Run list_symptom_categories first. This tool does NOT fetch anything itself.
RETURNS: {event_count, window, binning, classification, spikes
(strongest anomalous bins), spikes_total, hypotheses (ranked
root-cause candidates, each with a suggested_check), next_checks (which
skill/tool to run next)}. Read binning for the resolution you were
given, and classification for how much of the stream matched nothing —
the ranking describes only the part that did.
GOTCHAS: read-only, stateless, no network — nothing is executed. Remediation routes to vmware-aiops (single fix) or vmware-pilot (multi-step). A malformed event returns {error, hint} naming the offending index.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | How many ranked hypotheses come back (default 5). Spikes are capped separately at 20, true count in 'spikes_total'. | |
| events | Yes | Event envelopes, each {ts, source, severity, entity, text, fields}. ts may be ISO-8601, epoch seconds or epoch millis and is required; severity is normalised onto critical/error/warning/ info/unknown, so vendor spellings (fatal, red, warn, yellow, notice, green) are accepted. An entry that cannot be normalised is refused with its index, not skipped. | |
| bin_seconds | No | Time-bin width in seconds. Omit and it is chosen from event density off the ladder 1/10/60/300/900/3600/21600/86400, taking the finest width still averaging 4 events per bin. | |
| z_threshold | No | Standard deviations above the mean bin count that mark a spike (default 2.0). Under 3 bins, or a flat series, yields none at any threshold — empty spikes is not "calm". |
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.
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.
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.
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.
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.
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.
[READ] List the symptom categories vmware-debug recognises, each with example keywords and a suggested next check (which skill/tool to run). Takes no parameters. Use this when you don't yet know what to look at — it turns "something's wrong" into concrete investigation steps. Then gather the events those checks name and pass them to incident_timeline. Returns the family list envelope {items, returned, limit, total, truncated, hint}; each item is {category, example_keywords, suggested_check}. The routing table is a fixed constant, so truncated is always false and total exact — this is every category, not a page. Read-only; no network access.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
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.
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.
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.
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.
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.11.1case_closecase_getcase_gradecase_hypothesescase_knowledgecase_listcase_opencase_plancase_readinesscase_record_gapcase_submit_evidencecase_timelineincident_timeline5 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / bin_seconds / descriptionAdded value: +"Time-bin width in seconds. Omit and it is chosen from event density off the ladder 1/10/60/300/900/3600/21600/86400, taking the finest width still averaging 4 events per bin."Input schema / properties / events / descriptionAdded value: +"Event envelopes, each {ts, source, severity, entity, text, fields}. ts may be ISO-8601, epoch seconds or epoch millis and is required; severity is normalised onto critical/error/warning/ info/unknown, so vendor spellings (fatal, red, warn, yellow, notice, green) are accepted. An entry that cannot be normalised is refused with its index, not skipped."Input schema / properties / top_n / descriptionAdded value: +"How many ranked hypotheses come back (default 5). Spikes are capped separately at 20, true count in 'spikes_total'."Input schema / properties / z_threshold / descriptionAdded value: +"Standard deviations above the mean bin count that mark a spike (default 2.0). Under 3 bins, or a flat series, yields none at any threshold — empty spikes is not \"calm\"."list_symptom_categories1 field changedInput schema / additionalPropertiesAdded value: +falsev1.8.8incident_timelinelist_symptom_categoriesEach tool has a clearly defined role, and the case_* family is well delineated: open, get, submit evidence, record gap, grade, close, etc. The main ambiguity is between incident_timeline and case_timeline, and between list_symptom_categories and case_plan, though the descriptions do enough to distinguish them in most contexts.
Most tools share the case_ prefix, making the family recognizable, but the naming scheme mixes verb-first names like case_open and case_get with noun-style names like case_timeline, case_readiness, and case_knowledge. The two non-case tools also break the pattern: incident_timeline is noun-only and list_symptom_categories reverses the prefix ordering.
With 14 tools, the set is well-scoped for a case-investigation and evidence-grading workflow. Each tool occupies a distinct role in the lifecycle, and none feel redundant or decorative.
The tool set covers the full investigation workflow: open, plan, collect evidence, record gaps, manage hypotheses, timeline correlation, grading, and closing, plus supporting introspection tools for readiness, knowledge, and symptom categories. The intentional lack of fetch/update/delete is consistent with the server's stated role as an analysis and ledger layer over external data-source skills.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Discover software problems, analyze evidence, and create implementation-ready Build plans.
Causal reasoning for reliability: root cause, blast radius, and service health for agents.
Track errors, manage performance alerts, and configure dashboards and monitors
Multi-expert decision intelligence with transparent synthesis and auditable workflows.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/vmware-skills/VMware-Debug'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
