Skip to main content
Glama
vmware-skills

io.github.zw008/vmware-debug

by vmware-skills
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

grade_case

Computes and records the conclusion grade for a VMware investigation case by recomputing from the evidence ledger, not manual input.

Instructions

[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). Exclusion is per hypothesis, counting only sources that falsify THAT hypothesis; the case is Excluded only when every registered one is. A hypothesis contradicted but not yet ruled out holds the case at Candidate. Otherwise the grade counts only evidence that falsifies nothing.

RETURNS: {grade, previous, direction, reasons, ceiling, ceiling_reasons, rules_source, rules_origin, hypotheses}. hypotheses lists every registered hypothesis as {id, status: open|excluded}. 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
case_idYesThe case to grade (from open_case/list_cases). This is the only parameter — see above for why there is no grade parameter.

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 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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

Deploy Server

Other Tools