Learn an instrument

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

The description is genuinely informative: it discloses local file writes under ~/.local/share/pyvisa-mcp/ (or PYVISA_MCP_MEMORY), next-session reuse, and optional web fetching via fetch_manual. However, persisting files and searching the web conflicts with the declared readOnlyHint=true and openWorldHint=false, so the behavioral claims and the annotations are inconsistent.

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?

Three tight sentences, front-loaded with the core action before storage location and refresh behavior. No filler; each sentence adds a distinct fact (what it does, where it persists, how to refresh).

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 an output schema present, return values need not be described, and the description covers persistence, location override, cross-session reuse, and refresh flags. The remaining gap is the mismatch with the read-only/open-world annotations rather than missing description content.

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 explains deep, resource, manual_url, and fetch_manual in detail. The description only adds the refresh framing for deep/fetch_manual, which is a useful pointer but largely duplicates the schema; 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?

States a specific verb ('Build (or reload)') and resource ('a local brain for this exact *IDN?'), and clarifies what the brain contains (profile, remembered SCPI, manual text). It is distinguishable from siblings like list_learned_instruments and forget_instrument, though the 'local brain' metaphor is only loosely standard terminology.

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 implies when to run it (first-time setup or refresh) and notes the refresh flags, but never explicitly contrasts it with open_instrument, identify, or list_learned_instruments. Usage is inferable rather than stated as explicit when/when-not guidance.

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