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

With no annotations, the description carries the full burden and does real work: it discloses two execution modes, that the elicit path is blocking, and that the chat path returns payload the agent must relay and then submit back. It omits state side effects (whether an interview record/draft is created or how resume is detected), which keeps it short of a 5.

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?

Four sentences, front-loaded with the core action, then the conditional execution paths, then the adaptivity note; nothing is redundant. The parenthetical example list (cloud, throughput, availability, compliance, …) is mildly noisy but justifies the tool's value.

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 an interactive tool with no annotations and no output schema, the two execution paths and the hand-off to archforge_submit_answers cover the main things an agent must know. Gaps around resume semantics and prerequisite state keep it at 4 rather than 5.

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 50%: mode has an enum with a description, while projectId is undocumented in both schema and description. The description implies the elicit-vs-chat distinction that mode controls ("If the IDE supports popup forms"), but never maps mode values to behavior or explains what projectId must reference, so it adds only marginal meaning.

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?

"Run or resume the requirements interview" gives a specific verb plus resource and names archforge_submit_answers as the follow-on, so it is distinguishable from that sibling. It does not clarify its relationship to archforge_start_project (whether a project must exist first), leaving one adjacency to inference.

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 clearly branches usage: when MCP elicitation is available the questions arrive as native forms and the call blocks until answered; otherwise the agent must show the returned chat questionnaire and submit replies via archforge_submit_answers. That is actionable conditional guidance, though it never states the prerequisite project state or when to prefer this over archforge_status.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful context by calling the estimate 'deterministic' and listing its output components, but it says nothing about behavior when the project has no answers yet, whether the estimate is persisted, or any access requirements.

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?

A single dense sentence that front-loads the core action and then enumerates the concrete outputs. Nothing is wasted and no re-reading is required.

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 simple read-only, one-parameter tool with no output schema, the description does the essential work of specifying what the result contains. The main residual gap, given the absent output schema, is not explaining edge-case behavior when answers are incomplete.

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% and the description never mentions the single parameter, projectId, or what it identifies. The parameter name is largely self-explanatory, but the description fails to compensate for the documentation gap in the schema.

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 gives a specific verb ('Show') and resource ('capacity estimate') and enumerates exactly what the estimate contains (RPS, storage, instances, availability budget, consistency warnings). This makes it distinguishable from siblings like archforge_generate_design or archforge_status, though it never names those siblings explicitly.

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 phrase 'for the answers collected so far' implies the prerequisite that answers must already be submitted (e.g., via archforge_submit_answers), which is useful implied usage context. However, there is no explicit statement of when to choose this over archforge_generate_design or archforge_status, nor any note about calling it before answers are complete.

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

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

With no annotations, the description carries the full behavioral burden. It discloses two useful traits: API keys are rejected and test:true sends a tiny request to the resolved model. However, it does not say whether settings changes persist, require restart, are validated, or what the diagnostics output includes, leaving gaps for a mutation-capable tool.

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?

Three sentences, front-loaded with the primary purpose and then key constraints, with little waste. The sentence about test:true is well-placed at the end, though the parenthetical diagnostics list is slightly dense.

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 9-parameter, zero-required configuration tool with no annotations and no output schema, the description covers the core purpose, API key exclusion, and test behavior. It still omits what diagnostics return, what each setting affects, persistence behavior, and how the model/provider resolution interacts with llmMode, so an agent lacks enough context to call it optimally.

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 only 33%, so the description must compensate. It adds meaning for test, apiKeyEnv, and partially for model and question mode, but leaves baseUrl, llmMode, provider, outputDir, and sectionsPerCall unexplained beyond the schema's sparse enum hints. The description helps but does not fully close the coverage gap.

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 a specific dual purpose: show diagnostics (IDE support, model selection, question display) or change settings. This clearly distinguishes it from sibling tools like archforge_start_project or archforge_status, though 'change settings' is broad enough that an agent may still have to infer which settings are mutable.

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?

It explicitly scopes usage by saying API keys are never accepted here and pointing to the environment variable named by apiKeyEnv, which is a valuable when-not-to-use hint. It also distinguishes diagnostics from configuration changes, but it does not name alternative sibling tools or state prerequisites for changing settings.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that partial exports are permitted and that missing sections are marked, but it never says whether existing files in the target directory are overwritten or preserved — a critical unknown for a write operation — nor does it mention permissions or any return confirmation.

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, front-loaded with the concrete artifact list and followed by the behavioral caveat. The dense file enumeration is justified because it tells the agent exactly what lands on disk. No filler wording.

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 multi-artifact write tool with no output schema and no annotations, the description covers what is produced and the partial-export rule but omits overwrite semantics, prerequisites relative to sibling generation tools, and any success/failure signal. Adequate to invoke, incomplete for predicting side effects.

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 only 50%: outDir is documented in the schema, while projectId has no description anywhere. The description restates the default directory already present in the schema but adds no meaning for projectId (e.g., whether it scopes the source design or the output folder), so it does not compensate for the coverage gap.

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 ('Write') and enumerates the exact artifacts produced (hld.md, lld.md, README.md, requirements.json, viewer.html, .mmd diagrams) plus the default location. That makes the action concrete and distinct from generation-oriented siblings like archforge_generate_design. It stops short of explicitly naming which sibling precedes it, so differentiation is implied rather than stated.

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 when-to-use or when-not-to-use guidance and no named alternatives; the agent must infer that this is the post-generation step that persists artifacts to disk. The 'partial exports are allowed' clause hints at a valid condition for calling, but preconditions (e.g., whether a design must exist first) are never stated.

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

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

No annotations are provided, so the description carries the full burden, and it does well: it discloses the dual execution model (server-side model generation vs host-authoring mode returning section briefs), the iterative batching behavior ('a few sections' per call), and the completion signal. It does not mention permissions, cost, or rate limits, keeping it short of a 5.

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?

Front-loaded with the primary action and execution modes, then moves to the iteration loop and revision path. It is dense but every sentence adds operational value; the conditional mode explanation is slightly tangled but not wasteful.

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 multi-mode, iterative generation tool with no output schema, the description explains both execution paths, the looping protocol, and the revision mechanism - the essentials an agent needs to call it correctly. It leaves the return payload shape and how 'complete' is signaled largely implicit.

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 83% with all parameters described, so the baseline is 3. The description adds meaning for sectionIds and feedback (used to revise specific sections) and implies the loop semantics of repeated calls, but adds little beyond the schema's own regenerate and scope documentation.

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 a specific verb+resource ('Generate the design sections') and distinguishes it from archforge_submit_sections by explaining the host-authoring handoff. It doesn't fully clarify how HLD vs LLD generation is selected, though the scope enum in the schema covers that.

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?

Provides clear operational guidance: call repeatedly with the same arguments until completion, and use sectionIds + feedback to revise specific sections. The reference to archforge_submit_sections names the relevant sibling, but the trigger conditions among siblings (e.g., when to start vs regenerate) are only implied.

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

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

With no annotations, the description carries the load and does disclose non-obvious behavior: it creates persistent state and returns both a project id and an interview-question catalog used for pre-filling. It omits permission/auth requirements and what happens on duplicate names, but the mutation and return shape are clear.

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?

Three short sentences, front-loaded with the action, then the return value, then the next step. Nothing is repeated or 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?

For a two-parameter creation tool with no output schema, the description covers the action, the inputs' intent, and the return payload, which is everything an agent needs to invoke it and act on the 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 description coverage is 100%, so both parameters are already documented in the schema; the description adds only the framing that the description field is the user's idea driving the project and downstream pre-fill. That is marginal added meaning, matching the baseline 3.

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 and resource ('Create a new architecture-design project') and grounds the input ('from the user's app idea'), which cleanly separates it from siblings like archforge_generate_design or archforge_ask.

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 explicit sequencing ('Follow with archforge_ask') and implies this is the entry point of the workflow. It does not state when-not to use it (e.g., resuming an existing project via archforge_status), so it stops short of full routing guidance.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description carries a lower burden. It does add value by enumerating the payload: interview progress, per-section written/stale/missing states, how documents will be written, and the next step. It stops short of describing output shape, ordering, or what 'stale' means operationally.

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 conditional clauses, front-loaded by mode, with no filler. Every phrase maps to a distinct piece of behaviour or returned information.

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 read-only tool with one optional parameter and no output schema, the description covers both call modes and the kinds of content returned, which is enough to invoke it correctly. The remaining gap is conceptual (what 'how documents will be written' actually contains), which is minor given the tool's simplicity.

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 has to carry the meaning of the single optional projectId, and it does: absence means list all projects, presence means per-project detail. That is the key semantic an agent needs. It doesn't say what format a projectId takes or what happens if an unknown id is supplied.

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 splits the tool into two clearly named modes: a bare call lists all projects, and a call with projectId returns interview progress plus section states (written/stale/missing) and the next step. That is specific enough to distinguish it from siblings such as archforge_capacity or archforge_config, though it never names a verb for the tool itself and relies on its title 'Project status' for the framing.

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?

It states the condition that changes behaviour (projectId present or absent), which effectively tells the agent when each mode applies. However, it gives no guidance on when to choose this tool over siblings such as archforge_capacity for progress metrics or archforge_config for settings, so tool selection is left to inference.

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

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

With no annotations, the description carries the full burden, and it does disclose the return behavior (next question batch vs. completion announcement), which matters because there is no output schema. It says nothing about mutation effects, whether submission is idempotent, what happens to unsupplied questions, or how errors on bad question ids surface.

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?

Three tight sentences, front-loaded with the action and the mode list, with the constraint rule last. No filler, though the three-mode clause is dense enough that the user/inferred distinction has to be re-read against the final sentence.

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 6-parameter mutation tool with no annotations and no output schema, the description covers purpose, return shape, and one key constraint. It is still missing failure behavior (unknown question id), partial-submission semantics, and how the four answer-transport parameters interact, which an agent needs to call this correctly.

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%, so the schema already documents source, answers.id/value, useDefaultsFor, confirmInferred and acceptAllDefaults. The description restates the 'inferred' meaning and gestures at defaults, but leaves the risky ambiguity unresolved: when to use answers vs useDefaultsFor vs acceptAllDefaults vs confirmInferred, and whether these can be combined in a single call.

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 opens with a specific verb and object ("record the user's answers", "pre-fill inferred answers", "accept defaults") and states what comes back ("next batch of questions... or the interview is complete"). It is clearly distinguishable from a read/query sibling, but it never names a sibling such as archforge_ask or archforge_submit_sections to route between them.

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?

It gives an explicit behavioral rule for when to use which mode: "Only submit values the user actually gave; use source 'inferred' for values you deduced from their idea." That is real usage guidance, but there is no when-not guidance, no mention of when to call archforge_ask instead, and no prerequisites (e.g. must a project exist first?).

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

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

With no annotations, the description carries the full burden and does real work: it discloses server-side heading cleanup, Mermaid and required-content validation, partial storage semantics, and problem reporting. Gaps remain on permissions/auth requirements, whether resubmission overwrites existing sections, and the shape of the returned problems, which keeps it below 5.

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 sentences, front-loaded with the action and its source, followed by the server-side behavior. Every clause carries information about validation or storage outcomes; nothing is redundant.

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 mutation tool with no annotations and no output schema, the description covers the critical behavior: validation, partial acceptance, and problem reporting as the return channel. It could go further on auth/idempotency and on how the force flag interacts with the validation story described, but nothing essential is missing for a correct first call.

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 only 33%, and the description never mentions projectId or the important force flag, leaving the agent to rely on the schema alone for those. It does add meaning for sections' content by implying the body is markdown that will be heading-cleaned and Mermaid-validated, which is genuine added value, but the coverage gap is only partly compensated.

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 and resource ('Submit design sections') and ties the input to a named sibling, archforge_generate_design briefs, which separates it from archforge_submit_answers. It stops short of explicitly naming which sibling it is not, so a 4 rather than a 5.

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?

Clear upstream context: use this after obtaining briefs from archforge_generate_design. It also explains the partial-acceptance outcome (accepted sections stored, problems returned for the rest), which tells the agent how to react to a mixed result. No explicit when-not-to-use guidance or mention of the force escape hatch, so not a 5.

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