model_scanner__scan_directory

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

No annotations exist, so the description carries the full burden. It does disclose two genuinely useful behaviors: automatic exclusion of node_modules/.git/venv, and per-file risk reporting (with the 2000-file default living in the schema). It never states that the scan is read-only/non-mutating, says nothing about performance cost or timeouts on large trees, and does not describe the shape of the findings.

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?

Front-loaded with the verb and scope, then the extension list, then the skip behavior. The long enumeration of extensions is verbose but earns its place by telling the agent exactly which artifacts are in scope. Slightly dense in a single sentence.

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 no output schema and no annotations, the description should explain what a scan returns (findings list? per-file verdicts? severity?), and it only says 'report supply-chain risks in each.' Parameters are fully covered by the schema, so the gap is entirely on the return-value and safety side.

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 baseline is 3. The description contributes indirectly — the extension whitelist clarifies what the include/exclude substring filters operate against — but it says nothing about how include and exclude interact when both are supplied, nor about the maxFiles truncation consequence.

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 and resource ('Recursively scan a directory'), enumerates exactly which model file types qualify, and calls out the SavedModel-via-saved_model.pb special case. The directory scope makes it trivially separable from model_scanner__scan_file and model_scanner__scan_hf_repo.

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?

Usage is only implied by the resource type — an agent infers 'use this when you have a local directory, use scan_file for a single artifact.' There is no explicit when-to-use/when-not statement and no mention of the sibling tools by name, though the auto-skip list gives useful operating context.

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