audit_reconnaissance

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

No annotations are supplied, so the description carries the full burden. It does disclose one behavioral trait — it creates an inventory whose entries start as "not-yet-reviewed" — but says nothing about whether the repository is only read, where the inventory is persisted, whether reruns overwrite prior state, or what permissions are needed.

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?

A single sentence that front-loads the phase label and then lists the operations. There is no filler, though the comma-list style is terse enough that some meaning (what "classify" means) is compressed away.

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 annotations, no output schema, and two undocumented parameters, the description would need to explain inputs and the produced inventory. It instead describes only the internal activity, leaving the agent to guess at argument formats and the shape of the result before calling.

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% across two parameters. The phrase "repository metadata" loosely gestures at the required `repository` argument, but the `ref` parameter (branch/tag/commit?) is never mentioned, and no format, length, or default guidance is added beyond the bare schema types.

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 names concrete operations — map repository metadata and paths, classify files, build an inventory — and labels itself "Phase 1," which separates it from sibling readers like repository_tree and repository_read_file. It is clear what the tool does, though the boundary with repository_inspect is only implied by the extra classification/inventory step.

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?

"Phase 1" implies this is the entry point of an audit workflow, which is real usage signal. However, there is no explicit statement of when to prefer it over repository_inspect or repository_tree, and no exclusions or prerequisites (e.g., whether a prior snapshot must exist).

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