timps_code_archaeology

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'analyse git history' but doesn't disclose that it makes read-only operations, that it may be slow or expensive, or what exactly it produces (e.g., does it write files? Does it require network access?). It doesn't state any side effects or prerequisites like having a git repository locally. This is a significant gap for a tool that runs analysis.

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 single sentence that efficiently communicates the core purpose and outputs. It's not overly verbose and gets to the point. However, it could be structured better with a clearer breakdown of the three outputs, but given the brevity, it's acceptable. It doesn't waste words.

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?

This is a tool that performs complex analysis (AST graph, risk map, tribal knowledge) with no output schema and no annotations. The description provides only a high-level summary without detailing the exact behavior, limitations, or expected output format. With two parameters but no guidance on how to use them, the description is incomplete for an agent to use it effectively. It doesn't mention whether it returns a report, a structured file, or an in-memory result.

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 100%, meaning both parameters (request, language) are described in the schema. The description doesn't add any extra meaning beyond what the schema provides; it doesn't explain how 'request' should be phrased or what languages are supported. Baseline 3 is appropriate given high schema coverage, but it could have added examples of effective requests or clarified that language affects parsing.

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 clearly states the action (analyse git history) and the three outputs (AST import graph, risk map, tribal knowledge document). It distinguishes from siblings like timps_tech_debt_quantifier or timps_dependency_rebel by focusing on git history and producing a combined analysis, though it doesn't explicitly contrast with them. The resource is 'git history' which is specific enough.

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?

The description implies it should be used when you need a comprehensive understanding of codebase dependencies and risks from git history, but it doesn't explicitly state when to use it versus alternatives. For example, it doesn't say 'use this instead of timps_dependency_rebel for deeper context' or 'when you need tribal knowledge'. The request parameter allows plain-English task, but the description doesn't guide on what kind of requests are appropriate.

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