scan_local_program

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

With no annotations, the description carries the full burden and does substantial work: it discloses that list_tools actually starts and stops the server process, that no tool is executed, and that the report names settings but never their values. It doesn't cover failure modes (a server that hangs or won't start) or permission requirements for reading the settings file, so it stops short of full disclosure.

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 core action and the secret-detection scope are front-loaded in the first sentence, followed by a compact parameter block where every line carries new information. The pseudo-indented multi-line parameter list is a slightly awkward shape for a tool description but wastes little space.

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?

For a read-oriented scanner with no annotations, an output schema present, and a declared side effect (spawning a server), the description covers safety, consent, output privacy, and all parameters. The only real hole is that it doesn't position the tool against its siblings, which matters given scan_mcp sits right next to it.

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 coverage is 0%, so the description must compensate for all three parameters and it does: settings_file gets concrete example paths across Claude, Cursor, and Codex, server is defined as a name filter with its dependency on list_tools, and list_tools is explained behaviorally. An agent could fill this schema correctly from the description alone.

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?

Names a specific verb ('check') and a well-scoped resource (stdio/local-program MCP servers in an AI app's settings file), and spells out what it looks for: plain-text secrets and, optionally, tool listings. The scope is clear, but it never distinguishes itself from the sibling scan_mcp, which an agent will likely see alongside it.

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?

Gives conditional usage rules for parameters ('server: required for list_tools') and a consent gate ('Ask the person before setting this'), which is real guidance. What is missing is tool-selection guidance: nothing says when to pick this over scan_mcp or list_checks, or what to do when both could apply.

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