analyze_architecture

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

With no annotations provided, the description carries full disclosure burden. The key behavioral revelation—'skips rescanning' when using sessionId and 'triggers analysis' with path—is embedded in the schema parameter descriptions rather than the main description. The main description doesn't disclose side effects, return shape, cost implications of scanning, or any constraints. Given this is an analysis tool that may trigger heavy scanning work, more behavioral transparency about when rescanning occurs is warranted.

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 concise sentence that communicates the resource and the key usage preference. It's efficiently front-loaded with the essential decision (prefer sessionId). No wasted words, though it could arguably be slightly longer to differentiate from sibling analyze_* tools without losing conciseness.

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?

Among 22 siblings including many analyze_* tools (analyze_code_quality, analyze_complexity, analyze_testing, analyze_dependencies, etc.), this description doesn't clarify what distinguishes 'architecture' analysis from those. No output schema exists to explain what the 'architecture view' returns. The description is adequate for a tool with a clear primary use case but leaves the actual analytical output and distinction from siblings underspecified for an agent operating in a rich tool ecosystem.

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 67% (path and sessionId documented, limit undocumented). The description adds the key distinction that sessionId bypasses rescanning while path triggers analysis—valuable semantics beyond schema text. However, the 'limit' parameter (max 200) has no description in either schema or tool description, leaving its purpose ambiguous. The description partially compensates for coverage but the limit param remains unclear.

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 states it provides an 'Architecture view from a review_project session (or path)', which names a clear resource (architecture view) and its source. However, it doesn't specify what the architecture view contains, what analysis it performs, or how it differs from the other 'analyze_*' sibling tools (analyze_code_quality, analyze_complexity, etc.). The purpose is reasonably clear but not well differentiated from siblings.

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 explicitly says 'Prefer sessionId to avoid rescanning', giving clear usage direction. The parameter schema further clarifies that path 'triggers analysis' only when sessionId is omitted. This gives the agent a clear decision rule: use sessionId when you have a review_project session, fall back to path. It doesn't explicitly name alternatives or exclusions, but the preference guidance is actionable.

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