analyze_architectural_boundaries

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 two important behaviors: parsing happens 'locally' (no remote service) and that a graph can be saved to disk, implying a file-write side effect. It does not state whether the tool is read-only apart from outputPath, how it behaves on unparseable or large codebases, or what diagnostics look like.

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 tight sentences with the capability stated first and the output-control advice second; nothing is redundant. The phrasing 'Save a graph and return a summary' is slightly compressed and reads as an instruction rather than a description of the parameters that enable it.

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?

For a six-parameter analysis tool with no annotations and no output schema, the description covers the core capability and the size-control mechanism but omits what the summary or diagnostics contain and what happens on parse failures. It is adequate to attempt a call but not complete enough to predict results.

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 67%, and the description adds real meaning beyond it: 'inferred or declared C4 mappings' clarifies the interplay between c4Level and configPath, and 'Save a graph and return a summary' explains the outputPath/responseMode trade-off that the schema leaves undocumented for responseMode. Only tsconfigPath and error semantics remain unaddressed.

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 a specific verb and resource: it parses TypeScript/TSX dependencies and produces a graph with source evidence, C4 mappings, and diagnostics. It is clear what the tool does, but it never distinguishes itself from siblings like get_architecture_summary, query_architecture_graph, or render_architecture_graph, and it never explicitly ties the output to the 'architectural boundaries' framing in the tool name.

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?

There is no explicit guidance on when to use this tool versus the sibling analysis/render/query tools. The second sentence hints at a workflow (save the graph, return a summary) but does not name alternatives or state the conditions that would select one over the other, leaving the agent to infer that this is the entry point.

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