analyze_repository

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

The description discloses that it writes skills.sh and rules.md when output_dir is provided, and that history_depth affects git history analysis. However, without annotations, the description bears the full burden for behavioral disclosure; it does not state whether the tool is read-only (aside from optional writes), performance implications for large repositories, or any error behavior. This is partial but not comprehensive.

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 description is a conventional docstring format with a one-sentence summary and an Args block. It is concise and front-loaded with the main purpose, with parameter details efficiently listed. No fluff or redundancy.

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?

Covers the basic invocation (repo_url, history_depth, output_dir) and the fact that output is JSON, but 'engineering DNA' remains vague—what metrics or insights are returned is not specified. There is no mention of alternatives or when not to use it. An output schema exists, which may partially compensate, but the description alone leaves gaps for an agent deciding whether this tool fits.

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 fully explain parameters, and it does: repo_url, history_depth, and output_dir each receive a clear one-line explanation that goes beyond the bare schema titles. This fully compensates for the lack of schema-level descriptions.

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 ('Analyze') and resource ('a repository'), and indicates output ('engineering DNA as JSON'). Clear enough to distinguish from siblings like generate_skills or list_dimensions at a high level, though 'engineering DNA' is an opaque term that could leave an agent unsure what analysis is performed.

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?

No explicit guidance on when to use this tool versus alternatives like analyze_dimension or generate_skills. There is no mention of prerequisites, typical use cases, or conditions that rule this tool out. An agent would have to infer usage from context.

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