scan_target

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

The description states 'writes a new snapshot, violations, and drift events (vs the prior scan of the same target) to the local twin DB', indicating that repeated calls create new snapshots and change the state used for drift comparison. This contradicts the idempotentHint=true annotation, which implies repeated calls with the same arguments have the same effect. The description does add useful context about read-only vCenter API calls and local writes, but the contradiction forces a score of 1.

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 long but every sentence earns its place: parameter definitions, side effects, return values, coverage caveat, and performance warning. It is front-loaded with the [READ] tag and a clear summary, then structured logically with no repetition or fluff.

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 the tool has no output schema and only 2 parameters, the description carries the full burden and exceeds it: it explains return fields, side effects, how to inspect details, and crucial interpretation guidance about coverage. It is complete for an agent to select and invoke the tool correctly, aside from the annotation contradiction.

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 0%, but the description fully compensates by explaining both parameters: target is 'a vCenter target name as configured in vmware-aiops', and baseline is 'a baseline id from list_baselines' with a default value. This adds meaning beyond the bare schema, clarifying where values come from.

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 uses a specific verb ('Run a compliance scan') and resource ('vCenter target against a baseline'), clearly distinguishing this tool from siblings like list_baselines and list_violations. It also states the outcome ('persist results locally') and the return type, leaving no ambiguity about the tool's purpose.

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 explicitly references alternatives and complementary tools: baseline id should come from list_baselines, and details can be inspected via list_violations and list_drift_events. It also specifies when not to interpret violations=0 as compliance, and warns about long runtime on large inventories, effectively guiding when and how to use the tool.

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