scan_codebase

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

With no annotations supplied, the description carries the full disclosure burden. It is clear that this reads a local filesystem project and what categories of information it derives, which is useful context, but it never states that the operation is read-only, whether it writes anything to disk, or what happens on very large repos beyond the max_files default.

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?

Two sentences, front-loaded with the verb and then the detection list, with the usage cue trailing. The enumeration is long but each item is a distinct signal an agent would care about, so there is little waste.

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?

There is no output schema, and the detection list partially compensates by telling the agent what the result will contain. However, for a tool that takes a filesystem path, the missing guidance on path format and on the max_files cap leaves real gaps an agent could hit at call time.

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%, so the description must explain both parameters. "Local website project" loosely implies that path is a project directory, but no format, relative-vs-absolute guidance, or examples are given, and max_files is never mentioned at all, leaving a 3000-file cutoff undocumented.

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 ("Scan") and resource ("a local website project") and enumerates the artifacts it extracts: framework, routes/pages, meta tags, sitemap/robots, structured data, contact details, external links. It also distinguishes itself from the live-site sibling by noting it is for projects that aren't live yet.

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?

"Use when the site isn't live yet or to find what to fix in code" gives a clear selection condition that implicitly separates it from scan_site, which handles live sites. It stops short of naming scan_site explicitly or stating when not to use it, so it is strong context rather than a full routing rule.

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