generate_architecture

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

With no annotations, the description carries the full burden and does disclose the internal pipeline (technical planning, requirement alignment verification, document rendering), which is genuine context beyond structured fields. It is silent, however, on side effects an agent would care about: whether files are written to output_dir, overwriting behavior, or failure modes.

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 compact sentences, front-loaded with the key claim ('sole entry point'), with no filler. Slightly terse given the gaps, but nothing is wasted.

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?

An output schema exists so return values need not be explained, and the entry-point role is conveyed. Still incomplete: output_dir semantics and the file-writing side effect are unaddressed, and there is no annotation coverage to fall back on.

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 compensate. It explains session_id as coming from a completed requirements document, adding real meaning, but says nothing about output_dir (the default-empty optional parameter), leaving half the parameters undocumented.

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 the resource and role precisely: '架構書唯一入口' (the sole entry point for architecture documents) and that it renders an architecture document. This distinguishes it from generate_requirements and the other siblings, though it never uses an explicit verb like 'generate' for the resource itself.

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?

Gives a clear prerequisite: use the session_id of a completed requirements document (已完成需求書的 session_id), which implicitly routes the agent through generate_requirements first. No explicit when-not or named alternatives, but the usage condition is unambiguous.

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