Skip to main content
Glama
vmware-skills

io.github.zw008/vmware-debug

record_case_hypothesis

Register candidate explanations for a VMware debugging case and assign IDs for evidence or gap references; omit the statement to read their refuted, blocked, or open status.

Instructions

[WRITE] Register a candidate explanation — step 06. Called without statement it writes nothing and only reads the hypothesis ledger.

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 record_case_gap(blocks=[...]) and submit_case_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 grade_case'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 open_case/list_cases).
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. Addedv2.3.0

TDQS

A4.8/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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

There is no output schema, so the 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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.