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

Annotations cover the safety profile (readOnlyHint, openWorldHint, destructiveHint), so the bar is lower. The description adds material value beyond that: the Produces list enumerates exactly what artifacts are generated, including the tool-overload flag for >5 tools and the report_mode-gated analysis notes. It does not disclose processing time or any 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 summary followed by clearly demarcated USE THIS WHEN / NOT FOR / Produces / Args sections. Each line earns its place; no filler prose.

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 Produces section nonetheless previews them. Usage scope, parameter examples, sibling routing, and feature gating are all present. Nothing an agent needs to call this correctly is missing.

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 does so with example-laden Arg descriptions for all six parameters, showing expected format for pipeline_purpose, agents, tools_available, orchestration_approach, and memory_strategy, and gating report_mode to Pro/Team/Enterprise. It even documents a hidden constraint (tool overload at >5 tools) that no schema field expresses.

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+resource ('Design an AI agent pipeline or multi-agent orchestration system') and explicitly distinguishes itself from siblings by naming umlforge_stakeholder_arch, umlforge_api_sequence, and umlforge_event_driven with their conditions. An agent can route without opening any schema.

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?

Explicit USE THIS WHEN section lists three concrete triggers, NOT FOR section names three sibling tools and the scenarios each should handle. This is textbook when/when-not/alternatives routing.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and the description does not contradict them — a pure generation call is consistent with those hints. It adds value beyond the annotations by disclosing the report_mode entitlement constraint (Pro/Team/Enterprise only) and by spelling out the concrete deliverables (happy path plus two failure paths, dependency table, Design Score grading). It stops short of stating rate limits or any auth requirement beyond the tier note.

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-loads a one-line purpose, then layers USE THIS WHEN / NOT FOR / Produces / Args in scannable blocks with no filler sentences. The Produces list slightly overlaps the output schema, but it usefully sets expectations for a complex generative tool and costs little.

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-param generative tool with an output schema and full annotation coverage, this description supplies purpose, selection criteria, exclusions with alternatives, deliverable expectations, and per-parameter semantics. Nothing an agent needs in order to choose and invoke it correctly is missing.

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 carries the full burden — and it does: services is defined as all participants with a worked example string, user_journey as the action in plain English with an example, and report_mode as a boolean that additionally emits a Design Score report, including its availability restriction. All three parameters are unambiguous without 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?

States a specific verb and resource ("Diagram how services call each other") with an explicit scope limit ("for a specific user action or API flow"). The NOT FOR section names the four sibling tools it must not be confused with (reverse_engineer, event_driven, frontend_components, erd_schema), so an agent can differentiate it without opening any schema.

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 four concrete when-to-use scenarios (cross-service tracing, contract design, failure paths, QA/post-mortems) and four explicit exclusions that each route to a named alternative. There is no ambiguity about which tool to pick for event-driven or frontend work.

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?

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false, and the description does not contradict them. It adds genuine behavioral detail beyond the annotations: the report_mode paywall ('Pro/Team/Enterprise only') and the exact contents produced, including observability gap flags and risk notes. It stops short of disclosing generation latency, rate limits, or cost characteristics.

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?

Heavily front-loaded with purpose first, then usage, exclusions, and outputs; the USE THIS WHEN / NOT FOR / Produces scaffolding makes scanning easy. The Produces bullet list is longer than strictly necessary for tool selection, but each bullet is informative rather than filler.

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, yet the description still summarizes the return shape (diagram, pipeline flow, environment table, risk note, health report) and documents all inputs and the plan-gated mode. For a multi-parameter generative tool, nothing an agent needs to invoke it correctly is missing.

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 carries the full parameter burden, and it does so: all six parameters are documented with concrete example values (e.g. cloud_provider: 'Railway + Vercel', services: 'FastAPI API, Next.js, PostgreSQL, Redis'), which also conveys the expected comma-separated string format. It also calls out that cicd_tool is optional and gates report_mode by plan.

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 first line states a specific verb and two concrete resources ('deployment topology and CI/CD pipeline diagram'), and the NOT FOR section explicitly names rival siblings (umlforge_reverse_engineer, umlforge_threat_model, umlforge_api_sequence), so an agent can discriminate it without opening any schema.

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 provides an explicit 'USE THIS WHEN' block with three concrete scenarios and a 'NOT FOR' block that routes three adjacent use cases to named alternative tools. Both when-to-use and when-not-to-use are covered with alternatives.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: report_mode is gated to Pro/Team/Enterprise tiers, and it enumerates exactly what the output contains (erDiagram, schema narrative, integrity checklist, N+1 flags, Design Score). It does not address the idempotentHint=false implication that repeated calls may yield different output, which is the one remaining gap.

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 a one-line purpose, then organized under clear headers (USE THIS WHEN, NOT FOR, Produces, Args) with the routing guidance before the output details. It is longer than average, but nearly every line is load-bearing; the Args block is somewhat verbose relative to the compact schema it mirrors.

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 five-parameter generative tool with an output schema present, this is complete: inputs are explained with examples, the report_mode entitlement constraint is disclosed, and the produced artifact list tells the agent what to expect without duplicating the output schema verbatim. Nothing an agent needs to invoke and interpret this tool is missing.

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 carries the full burden and does so: each of the five args is documented with meaning, concrete examples ('User(id, email, tier), Order(id, user_id, status, total)'), defaults (PostgreSQL), and inter-parameter relationships (access_patterns is optional and feeds index recommendations; report_mode additionally produces a Design Score report). This fully compensates for the empty schema descriptions.

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 resource: 'Design a database schema with ERD, integrity rules, and index recommendations.' It names the artifacts produced and explicitly differentiates itself from sibling tools via the NOT FOR section. An agent can distinguish this from umlforge_reverse_engineer or umlforge_api_sequence without opening any schema.

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?

Explicit USE THIS WHEN bullets state the triggering conditions (designing/reviewing a schema, needing an ERD, wanting index recommendations) and NOT FOR routes three adjacent scenarios to named alternatives with the reason each applies. This is textbook when/when-not/alternative 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful output-shape context (retry loops, DLQ handling, failure mode analysis, report_mode gating) but does not disclose runtime behavior beyond that, such as generation time, determinism, or external calls. Given the annotation coverage, a 3 is appropriate.

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?

Tightly structured with single-line bullets under USE THIS WHEN, NOT FOR, Produces, and Args. Every line is front-loaded and adds distinct information; no filler or repetition of the tool name.

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 design-generation tool with six parameters, required/optional split, an output schema, and rich annotations, the description covers purpose, exclusions, expected artifacts, and parameter intent. Nothing an agent needs to invoke or route this tool is missing.

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 carry the burden. It documents all six parameters with examples for producers, consumers, broker, and events, and explains report_mode with its entitlement constraint. system_context is described as intent rather than format, which is the only minor 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 opens with a specific verb and resource: 'Design an event-driven or async messaging architecture (Kafka, SQS, RabbitMQ, etc.)'. It also explicitly names which sibling tools to use for adjacent concerns (umlforge_api_sequence, umlforge_state_machine, umlforge_stakeholder_arch), so an agent can disambiguate without inspecting schemas.

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 explicit USE THIS WHEN and NOT FOR sections that name the exact alternative tool for each excluded scenario (synchronous REST/gRPC, entity lifecycle, full system architecture). This goes beyond when-to-use into when-not and how-to-route, leaving nothing 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?

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds real context beyond that: the full list of artifacts produced, the god-component flagging behavior, and a tier requirement for report_mode ('Pro/Team/Enterprise only'). It doesn't disclose rate limits or generation latency, so not 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 one-line purpose followed by scannable USE THIS WHEN / NOT FOR / Produces / Args sections. Sized appropriately for a generator tool, though the Args block partly restates schema property names.

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 needn't be spelled out, yet the description still enumerates the deliverables, which helps selection. All five parameters are addressed and the tier gate on report_mode is flagged. Nothing an agent needs to invoke this correctly is missing.

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, and it largely does: it documents the supported framework values (React, Vue, Angular, Svelte, Next.js), state-management options, an example for interactions, and the meaning of report_mode. Only feature_description lacks added guidance, but it is self-evident.

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+resource ('Design a frontend component tree and interaction flow for a UI feature') and immediately distinguishes itself from sibling tools by name in the NOT FOR section. An agent can route to this tool without opening the schemas of the alternatives.

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?

Explicit USE THIS WHEN conditions and NOT FOR exclusions, each routing to a named sibling (umlforge_api_sequence, umlforge_reverse_engineer, umlforge_stakeholder_arch). This is textbook when/when-not/alternative 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?

Annotations already cover readOnly/openWorld/idempotent/destructive, and the description adds meaningful context beyond them: report_mode is gated to Pro/Team/Enterprise, github_token is 'never stored or logged', and inputs are mutually exclusive ('Provide EITHER github_url OR legacy_code — not both'). It also enumerates the concrete artifacts produced (diagrams, 6-phase roadmap, risk flags), which is the kind of behavioral disclosure an agent needs.

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?

Despite its length, the description is front-loaded with a one-sentence purpose and then cleanly sectioned (USE THIS WHEN / NOT FOR / Produces / Args). Every bullet earns its place by disambiguating scope, output, or parameters; there is no filler prose.

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 7-parameter, multi-artifact tool, the definition is complete: inputs, mutual-exclusivity constraint, deliverable list, tier gating, and auth handling are all present. Since an output schema exists, return values needn't be re-explained, and the description's output summary is a useful complement rather than redundant padding.

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 carries the full burden — and it does. Every one of the 7 parameters is documented: accepted github_url URL formats, the full supported list for source_language and target_language (with defaults), system_purpose's effect on labels/advice, github_token's scope requirement, and report_mode's semantics and tier restriction.

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 opening sentence states a specific verb+resource: 'Visualise a legacy codebase and produce a migration roadmap to a modern language.' The NOT FOR section explicitly differentiates from siblings by name (umlforge_reverse_engineer for modern code, umlforge_erd_schema for DB schema), so an agent can select this tool without opening any schema.

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 'USE THIS WHEN' block enumerates concrete triggers (specific legacy languages, pre-migration structural understanding, modernisation pitching) and the 'NOT FOR' block names the alternative tools to route to instead. This is exactly the when/when-not/alternatives pattern, with nothing 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?

Annotations already supply the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds non-obvious constraints on top: current_diagrams is REQUIRED and the tool cannot generate from scratch, output is limited to affected sections with %% changelog headers, and report_mode is gated to Pro/Team/Enterprise. It does not discuss how the diff is computed or failure modes on malformed Mermaid input.

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?

Long but deliberately sectioned with headers and front-loaded purpose; nearly every line carries actionable information. The trailing 'Produces' list partially overlaps the output schema, which is the only mild redundancy.

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 4-parameter generative tool with an output schema, the definition covers prerequisites, scope, alternatives, artifacts, and gating. Nothing an agent needs in order to call it correctly is missing.

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 carries the full burden and does so: all four parameters are documented with meaning, both required params are marked REQUIRED, and it specifies paste format ('including the ```mermaid fences') plus the tier restriction on report_mode.

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?

Opens with a specific verb+resource ('Update diagrams you already have to reflect what changed in a sprint or PR'), and explicitly names the sibling tools it is not (umlforge_reverse_engineer, umlforge_stakeholder_arch). An agent can distinguish it from all 13 siblings without opening a schema.

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 USE THIS WHEN / NOT FOR blocks give explicit triggers and explicit exclusions, and route each excluded case to a named alternative tool. This is about as complete as routing guidance gets.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety profile is covered. The description adds useful output-shape detail (what the package contains) and a tier constraint (Pro/Team/Enterprise only for report_mode) beyond annotations. However, with output schema present and annotations covering safety, this is solid but not rich behavioral disclosure.

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 core purpose, then clearly sectioned USE THIS WHEN / NOT FOR / Produces / Args. Every sentence earns its place; no filler. Bullet structure makes it skimmable.

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?

Output schema exists so return values needn't be explained, yet the Produces section still helpfully previews output artifacts including report_mode extras. Parameter guidance compensates for 0% schema coverage. Minor gap: no note on idempotency or openWorld behavior beyond annotations.

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 carry parameter meaning. It does document all five parameters with examples (e.g. tech_stack = "FastAPI, PostgreSQL, React, Railway"), notes pain_points is optional, and explains report_mode's effect and tier restriction. Slight gap: key_workflows says "2-3 flows" which is helpful but system_description guidance is thin.

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+resource ("Create a day-one knowledge-transfer package for a developer joining a team") and the NOT FOR section explicitly names sibling tools (umlforge_reverse_engineer, umlforge_stakeholder_arch, umlforge_api_sequence) with the disambiguating condition. An agent can route to the correct UMLForge tool without opening schemas.

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?

USE THIS WHEN gives three concrete triggering scenarios and NOT FOR names three alternative tools with the condition that selects each. This exceeds typical when-to-use guidance by covering both inclusion and exclusion criteria.

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?

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds genuinely non-structured context: the github_token requires repo scope and is 'never stored or logged', report_mode is gated to Pro/Team/Enterprise, and the exact artifact set produced (including optional state diagram and A–F health scores) is spelled out.

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?

Well front-loaded with headed sections (USE THIS WHEN / NOT FOR / Produces / Args) so an agent can scan to the relevant part. Long but every block earns its place; the only blemish is mojibake in the em-dashes and ranges ('A?F', '5?50'), which does not obscure meaning.

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?

Despite an output schema existing, the description still fully describes the deliverable set, so an agent understands both invocation and result. Combined with the parameter detail and sibling routing, nothing an agent needs to call this correctly is missing.

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 carries the full burden and does so thoroughly: accepted github_url formats, the intended use of codebase for pasted/private code, max_nodes default 20 with range 5–50, token scope, and report_mode semantics. It also states the mutual-exclusion rule ('Provide EITHER github_url OR codebase — not both') that appears nowhere 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?

States a specific verb+resource ('Analyse an existing codebase and produce UML class, sequence, and state diagrams') and immediately enumerates the concrete outputs. It distinguishes itself from every relevant sibling by naming umlforge_stakeholder_arch, umlforge_living_docs, umlforge_erd_schema, and umlforge_api_sequence as the tools to use instead for adjacent jobs.

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 contains explicit USE THIS WHEN and NOT FOR sections, with each exclusion routed to a named alternative tool and the selecting condition. An agent can decide between this and all four adjacent siblings without opening another schema.

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?

Annotations already declare readOnly=true and openWorld=true, so safety is covered. The description adds real value beyond that: it enumerates the produced artifacts (Context/Container/Component) and discloses a licensing gate (report_mode is Pro/Team/Enterprise only), plus the extra Communication Notes output. It stops short of noting determinism/idempotency behavior, so not a full 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 one-line purpose followed by clearly labeled USE THIS WHEN / NOT FOR / Produces / Args sections. Every bullet adds routing or behavior value; no filler sentences.

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 the description need not explain return values, yet it still summarizes the diagram outputs. Combined with full parameter documentation and tier gating, an agent has everything needed to invoke 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 description coverage is 0%, so the description must carry all meaning, and it documents all three parameters with substance: system_description (what/who/components), audience_description (with examples), and report_mode (semantics plus the Pro/Team/Enterprise restriction). It does not specify format/length expectations, so a 4 rather than 5.

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 (Generate), resource (C4 architecture diagram), and scope (mixed technical/non-technical stakeholder audience). The NOT FOR section names the exact sibling to use for adjacent tasks, so an agent can distinguish it from umlforge_api_sequence, umlforge_deployment, etc. without opening any schema.

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?

Explicit USE THIS WHEN bullets give concrete triggering scenarios (CTO/investor/board presentations, high-level system picture), while NOT FOR routes four alternative tasks to their correct siblings. Nothing about when-to-use vs when-not 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered; the description adds value beyond that by disclosing the artifact set produced (stateDiagram-v2, transition table, implementation notes) and an access restriction — report_mode is Pro/Team/Enterprise only. It does not explain idempotency behavior despite idempotentHint=false, but it does not contradict it either.

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?

Content is front-loaded (one-line purpose, then routing, then outputs, then args) and every section is skimmable. It is on the long side for a five-parameter tool, and the output inventory is somewhat verbose given an output schema already exists, but no sentence is filler.

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 design-generation tool with zero schema descriptions and an available output schema, the description closes every gap an agent needs: what it produces, when to pick it over three named siblings, what each input means, and the tier gate on report_mode. Nothing required for correct invocation is missing.

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 carries the full burden and does so: every one of the five parameters is annotated with intent and a concrete example, including the comma-separated format implied by "pending, active, suspended, cancelled". Optionality is marked ("business_rules: ... (optional)") and the gated report_mode is explained with its tier requirement.

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 opening line states a specific verb and artifact ("Design a state machine") scoped to "a domain entity that has a lifecycle," which immediately separates it from diagram generators for APIs, ERDs, or deployments. The separate NOT FOR block names the exact sibling tools to use instead, so the agent can discriminate without opening any schema.

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?

Unusually complete routing guidance: USE THIS WHEN lists three concrete trigger conditions with a worked example (Order: pending → active → cancelled), plus the analytical goal (finding missing states, invalid transitions, race conditions). NOT FOR explicitly redirects three adjacent use cases to umlforge_api_sequence, umlforge_event_driven, and umlforge_reverse_engineer by name.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: it returns a recommendation plus a ready-to-run call rather than executing anything, and enumerates the four parts of the response (tool name, parameters, rationale, alternative). It is silent on rate limits, failure modes, or what happens when no tool matches, 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?

Front-loaded with 'START HERE if you are unsure which tool to use,' then organized into steps, use cases, examples, and args — easy to scan. Mild redundancy: the Args paragraph restates 'plain-English description' already covered in the opening and in the input examples, and the step list partially repeats the 'USE THIS WHEN' bullets.

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 the description needn't enumerate return values, and it instead explains the shape of the recommendation at the right level. Combined with the annotation-covered safety profile and the explicit routing guidance, an agent has everything needed to call this correctly on the first try.

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% for the single free-text parameter, so the description carries the full burden — and it does: 'Plain-English description... Include any relevant details: URLs, entity names, service names, tech stack — the more context, the better the pre-filled parameters.' It also supplies four concrete example inputs that model the expected shape and specificity.

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 purpose — route a plain-English goal to the correct UMLForge tool and return a pre-filled call — and explicitly positions itself against the 13 sibling tools ('not sure which of the 14 tools to use'). An agent can distinguish this router from umlforge_erd_schema or umlforge_threat_model without opening any schema.

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?

Contains an explicit 'USE THIS WHEN' block with three concrete trigger conditions, including the meta-condition ('you are not sure which tool to use') and the alternative behavior it replaces ('avoid trial and error with the wrong tool'). Nothing about when to invoke it 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?

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavioral context the annotations cannot convey: report_mode is gated to 'Pro/Team/Enterprise only' and expands the artifact set substantially. It does not mention latency, rate limits, or cost of a full STRIDE pass, so it falls 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?

Well front-loaded with the purpose first, then USE/NOT-FOR, then Produces, then Args. Slightly padded: the 'Produces' block largely restates what the output schema already structures, and the long bullet list of report contents could be tighter.

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, yet the definition adds depth by enumerating the artifact types (auth-flow sequence diagram, DFD with sensitivity labels, 6-category STRIDE table, critical flags, optional assessment report). Combined with when/when-not routing and license gating, an agent has everything needed to decide and invoke 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 description coverage is 0%, so the description carries the full parameter burden, and it does: every one of the 6 params gets an explanation with concrete examples ('JWT Bearer token', 'OAuth2 + PKCE', ['public internet ? API', 'API ? database']), and the four optional params are marked as such. This fully compensates for the empty 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 opens with a specific verb+resource+methodology: 'Generate a full STRIDE security threat model for a system.' It also names the sibling tools it is NOT (umlforge_reverse_engineer, umlforge_deployment, umlforge_api_sequence), so an agent can disambiguate without inspecting other schemas.

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?

Explicit 'USE THIS WHEN' triggers (pre-launch vuln identification, auth-flow documentation, pen-test/compliance prep) and an explicit 'NOT FOR' section that routes to the correct alternatives with the discriminating condition (e.g. report_mode=True for general architecture review). Nothing 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.