Skip to main content
Glama
vmware-skills

io.github.zw008/vmware-debug

case_hypotheses

Register a candidate root-cause explanation or read the hypothesis ledger for a VMware debugging case. See at a glance which theories are refuted, blocked by gaps, or still open.

Instructions

[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: refuted (ruled out by case_grade's rule), blocked (a gap is in the way, with the gap id and how to close it), or open. refuted_by lists every falsifying item; the first next step says when more sources are needed. Status is computed from what points at the hypothesis, never asserted.

GOTCHAS: refuted outranks blocked. Once an observation settles the question, a missing measurement no longer matters.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
case_idYesThe case whose hypothesis ledger this is (from case_open/case_list).
statementNoThe 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.13.0
    • changedInput schema / title
      Previous value: -"_case_hypotheses_implArguments"New value: +"case_hypothesesArguments"
  2. Addedv1.11.1

TDQS

A4.7/5.0
Behavior5/5

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

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

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

Conciseness5/5

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

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

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

Completeness5/5

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

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

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description reinforces the statement param's dual mode and adds the useful note that status has no parameter, but most of this is already present in the schema, so the description adds only moderate extra meaning.

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

Purpose5/5

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

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

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

Usage Guidelines5/5

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

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

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