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: the exact artifacts produced (sequence, component map, responsibility matrix, risk note), the ⚠️ tool-overload heuristic, and the plan-gating that report_mode requires Pro/Team/Enterprise. It does not explain persistence or whether generated diagrams are saved, which openWorldHint implies.

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 and header-segmented so an agent can skim purpose, routing, outputs and args in order. The Produces list and Args block are lengthy, but with 0% schema coverage the per-parameter prose is doing necessary work rather than padding.

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 generation tool with an output schema, the description covers the required inputs, all optional inputs, the plan-tier constraint on report_mode, and the downstream artifacts. Nothing needed to invoke it correctly is missing, and return values are correctly left to the output schema.

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 it: each of the six parameters gets an explanation plus a concrete example, including which are optional and how report_mode's omission falls back to a saved account preference while False forces diagrams-only.

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 resource ('Design an AI agent pipeline or multi-agent orchestration system') and the NOT FOR block names the exact sibling to use instead for each adjacent scenario, so 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 / NOT FOR structure gives three concrete trigger scenarios and three named alternatives (umlforge_stakeholder_arch, umlforge_api_sequence, umlforge_event_driven) with the condition that selects each. 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.

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

Annotations already declare readOnly/not-destructive/open-world, and the description adds genuinely new behavioral context: report_mode is gated to Pro/Team/Enterprise, omitting it falls back to a saved account preference, and the output enforces at least two failure paths with activation boxes and sync/async arrows. Some of the 'Produces' bullets overlap the output schema, so it stops 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?

Header-delimited sections put purpose and routing first, and the Args block is tightly annotated. Slightly long, with the 'Produces' bullet list partially restating what the output schema already conveys, which costs a point on strict economy.

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 complex diagramming tool the definition covers routing, inputs with examples, output shape, tier limits, and failure-path requirements. With an output schema and full annotation coverage already present, nothing material 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 must carry the full burden, and it does: services and user_journey each get a concrete example, and report_mode explains the True semantics, the tier restriction, the omit-to-use-preference default, and the explicit False behavior. This fully compensates for undocumented schema properties.

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') qualified by scope ('for a specific user action or API flow'). The NOT FOR section names four siblings and the exact condition that routes to each, so the agent can distinguish it from umlforge_reverse_engineer, umlforge_event_driven, umlforge_frontend_components, and umlforge_erd_schema 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?

Provides an explicit USE THIS WHEN list of four concrete scenarios plus a NOT FOR list that names the correct alternative tool for each exclusion. When-to-use, when-not, and alternatives are all spelled out with no inference required.

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 is covered. The description adds genuinely new behavioral context: report_mode is gated to Pro/Team/Enterprise, omitting it falls back to a saved dashboard preference, and False forces diagrams only. It does not mention persistence of generated diagrams or latency, but the tier-gating detail is meaningful beyond the annotations.

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: purpose sentence first, then when/when-not, then outputs, then args. The 'Produces' block runs six bullets and overlaps with the existing output schema, which is mild redundancy, but every section is scannable and labelled.

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 generation tool, the definition covers purpose, alternatives, output contents, tier gating, and every argument with an example. The output_schema already exists, making the 'Produces' enumeration partly redundant, but nothing an agent needs in order 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% across 6 parameters, so the description carries the full burden — and it does, supplying an example value for every argument (cloud_provider: 'AWS', 'Railway + Vercel'; environments: 'development, staging, production'; cicd_tool: 'GitHub Actions'). It stops short of format rules such as delimiters or max lengths, but the examples are the operative guidance an agent needs.

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 gives a specific verb+resource: generate a deployment topology and CI/CD pipeline diagram. The 'NOT FOR' section explicitly names three sibling tools and the neighbouring concerns they cover, so 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?

Three 'USE THIS WHEN' bullets describe when the tool fits (infrastructure visualisation, pipeline documentation, DR/DevOps planning) and three 'NOT FOR' bullets name the alternatives (umlforge_reverse_engineer, umlforge_threat_model, umlforge_api_sequence) with the condition that selects each.

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 is covered; the description adds genuine behavioral context beyond them, notably the report_mode Pro/Team/Enterprise tier gate and the 'omit to use saved account preference' fallback. It does not add rate limits or async/latency behavior, and the 'Produces' list partly duplicates the output schema.

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 purpose followed by scannable headers; every section is short. Minor redundancy: the 'Produces' bullet list restates content already delivered by the output schema, so it doesn't fully earn its space, though the Args block is necessary given zero schema coverage.

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 5-param generative tool with an output schema, the description supplies the routing rules, the optionality and defaults of inputs, and the account-tier constraint on report_mode. Nothing an agent needs 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 parameter burden and does so: each of the five args is documented with intent and concrete examples (domain_description, entities with typed attribute examples), access_patterns is marked optional with its use (index recommendations), db_technology has a stated default, and report_mode's tri-state semantics and tier restriction are explained.

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 database schema with ERD, integrity rules, and index recommendations') and explicitly names the sibling tools it is not for (umlforge_reverse_engineer, umlforge_api_sequence, umlforge_event_driven). An agent can route correctly 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?

Has structured USE THIS WHEN and NOT FOR sections with named alternatives and the conditions selecting them (full codebase analysis → reverse_engineer, service API flows → api_sequence, event pipelines → event_driven). This is explicit when/when-not/alternatives coverage.

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: the exact artifacts produced (sequence flow with ack/retry/DLQ, event catalogue, choreography-vs-orchestration assessment, failure mode table) and the plan gating for report_mode (Pro/Team/Enterprise plus the dashboard-preference default). It does not clarify whether output is persisted as a document or returned transiently, which is the 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?

Strongly front-loaded and header-scaffolded (USE THIS WHEN / NOT FOR / Produces / Args), so an agent can scan to the decision-relevant lines. It runs somewhat long overall, and the Produces list restates artifacts partly implied by output_schema, but nothing is padding.

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 generative design tool with an output schema and read-only annotations, the definition covers purpose, routing, inputs and deliverables adequately. The one soft spot is that report_mode's relationship to the rest of the output and any plan/quota consequences are only partially spelled out.

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 entire burden, and it does: every one of the six parameters is documented in the Args block with meaning plus concrete examples (e.g. producers: 'Order Service emits order.placed'; broker: 'Kafka', 'AWS SQS/SNS'). report_mode's optionality and null-default behavior (omit → saved preference, False → diagrams only) are explained in a way the bare anyOf/null schema cannot convey.

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 sentence states a specific verb+resource: 'Design an event-driven or async messaging architecture', with concrete technology examples (Kafka, SQS, RabbitMQ). The NOT FOR block explicitly names and contrasts three sibling tools (umlforge_api_sequence, umlforge_state_machine, umlforge_stakeholder_arch), so an agent can disambiguate 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?

USE THIS WHEN lists three concrete triggering conditions (event/message-based communication, event sourcing/CQRS/pub-sub, producer→broker→consumer flows), and NOT FOR routes the three most likely confusions to named alternatives. This is the full when/when-not/alternatives pattern.

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, so the safety profile is covered. The description adds real context beyond that: the tier gating on report_mode (Pro/Team/Enterprise only), the fallback to a saved dashboard preference when omitted, and the concrete artifacts produced (god component flags, accessibility notes). It does not mention auth beyond tiers or rate limits, so it stops 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-loads the purpose, then uses clear headers (USE THIS WHEN / NOT FOR / Produces / Args) so the content is scannable. It runs long, and since an output schema exists, the six-item Produces list is partly redundant, but each block still carries distinguishing information 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?

Given a 5-parameter generation tool with an output schema present, the description covers purpose, routing to alternatives, tier constraints, parameter semantics, and expected artifacts. Nothing an agent needs to select or 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%, yet the Args section documents all five parameters with meaning and examples: supported frameworks are listed, interactions comes with an example ('user submits form, table sorts on header click'), state_management names concrete libraries, and report_mode explains the True/omit/False trichotomy plus the tier requirement. This fully compensates for the empty schema coverage.

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 ('Design a frontend component tree and interaction flow for a UI feature') and immediately distinguishes itself from three siblings via the NOT FOR section. An agent can tell it apart from umlforge_api_sequence, umlforge_reverse_engineer, and umlforge_stakeholder_arch 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 conditions (React/Vue/Angular/Svelte feature, wanting hierarchy/props/state visibility, god-component detection) and explicit NOT FOR exclusions that route to named alternatives. This is the full when/when-not/alternative triad.

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?

Goes well beyond the annotations (which only cover read-only/safety hints) by disclosing polling semantics: waits ~45 seconds, may reply 'still generating' again with the same job id, and results are retained for one hour. These are non-obvious behaviors an agent must know to invoke it correctly and to retry.

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, then scannable WHEN/NOT FOR sections and the polling behavior. Every sentence carries actionable information; nothing is padded.

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 described. Combined with the polling/timeout/retention details and the job_id origin, the description covers everything needed to call and re-call this tool.

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 0% and the schema only labels the field 'Job Id'. The description compensates by telling the agent where the value comes from (the job id returned in the 'still generating' reply), which is the one piece of semantics that matters here.

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 with scope ('Retrieve the result of a UML Forge generation that was still running'). The 'still running' qualifier distinguishes it from the umlforge_* generation siblings that actually produce diagrams.

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 (the 'still generating' reply, fetching an earlier result) and NOT FOR routing (starting a diagram vs. umlforge_suggest for tool choice). The agent is told exactly which condition selects this tool and which siblings to use otherwise.

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, destructiveHint=false), and the description adds genuinely non-obvious behavior: report_mode is gated to Pro/Team/Enterprise, github_token is only needed for private repos and is never stored or logged, and exactly one of github_url/legacy_code must be supplied. The tier restriction and credential-handling disclosure are the kind of context annotations cannot express.

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 summary followed by clearly labeled USE THIS WHEN / NOT FOR / Produces / Args sections. It is long, and the 'Produces' list partially duplicates the output schema, but the structure is scannable and nothing 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 7-parameter, zero-required tool with an output schema, the description supplies the missing pieces an agent needs: mutually exclusive input rule, credential scope, tier gating, and default language pair. Nothing required to invoke it correctly is absent.

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: every argument is explained with defaults, supported values, the accepted GitHub URL formats, and the either/or exclusivity rule for github_url vs legacy_code. 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?

States a concrete verb+resource ('Visualise a legacy codebase and produce a migration roadmap') and immediately distinguishes itself from siblings by naming umlforge_reverse_engineer and umlforge_erd_schema as the wrong tools for adjacent tasks. An agent can route to it without opening the 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' list enumerates the source languages and intents, and the 'NOT FOR' block names each alternative tool and the condition that selects it. The only unimplemented case (source-code generation) is flagged as a future feature rather than left ambiguous.

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, idempotentHint=false, so the safety profile is covered; description is consistent with a compute-and-return operation. It adds genuinely non-structured context: report_mode's Pro/Team/Enterprise tier gate, the default-from-dashboard-preference behavior, and the exact set of artifacts produced (changelog headers, evolution notes, Analysis Notes).

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-structured and front-loaded with the purpose before the routing rules, and headers make scanning easy. Slightly verbose: the 'Generating diagrams without existing ones to update → use any other tool' bullet and the IMPORTANT restatement of the required-parameter rule duplicate points made elsewhere.

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?

Given an output schema exists, the description need not explain return values, yet it still summarizes the produced artifacts so the agent can set expectations. Inputs, prerequisite state (must already have diagrams), and tier constraints are all covered for a 4-parameter tool.

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 0%, so the description carries the full burden, and it does: it documents all four parameters with semantics beyond the schema titles — current_diagrams (required, full Mermaid content including fences), sprint_changes (new/removed/renamed/modified), affected_files (optional scope), and report_mode (boolean, tier-gated, omit-to-use-saved-preference). 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?

States a precise verb and resource ('Update diagrams you already have to reflect what changed in a sprint or PR') and explicitly names the siblings it is not (umlforge_reverse_engineer, umlforge_stakeholder_arch). An agent can distinguish it from all 13 siblings from the description alone.

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 explicit 'USE THIS WHEN' and 'NOT FOR' sections, routing the agent to the correct alternative for each excluded case (first-time generation → reverse_engineer or stakeholder_arch; GitHub URL → reverse_engineer). 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.

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's job is to add context it does. It does: it discloses the report_mode plan gating (Pro/Team/Enterprise only) and the saved-preference fallback when omitted, plus the concrete artifacts produced. It stops short of stating latency, cost, or whether report_mode changes output size materially, 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?

Structure is strong and front-loaded: one-line purpose, then USE WHEN, NOT FOR, Produces, Args. The Produces list is slightly longer than strictly necessary, but each bullet describes a distinct artifact the agent may need to reason about, so little 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?

With an output schema present the description need not explain return values, yet its Produces section aligns cleanly with what is generated. Combined with the explicit when/when-not routing and complete arg documentation for a 5-param, 3-required tool, an agent has everything needed to invoke it 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 does so: every one of the five params is documented in the Args block, with format examples for tech_stack, a cardinality constraint for key_workflows ("2–3 flows"), optionality flagged for pain_points, and full semantics plus plan/toggle interaction for 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?

The first line gives a specific verb+resource+audience: "Create a day-one knowledge-transfer package for a developer joining a team." The NOT FOR section explicitly names the sibling tools it must not be confused with (reverse_engineer, stakeholder_arch, api_sequence), so an agent can disambiguate without opening 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 bullets cover the three triggering scenarios (new joiner, handoff, gathering gotchas/diagrams). The NOT FOR block routes three adjacent intents to the correct siblings, giving both positive and negative usage conditions with no inference required.

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, so the safety profile is covered. The description adds genuinely useful context beyond them: github_token is never stored or logged, report_mode is gated to Pro/Team/Enterprise and falls back to a saved dashboard preference, and github_url/codebase are mutually exclusive. It does not address the non-idempotent hint or cost/latency of scanning a large repo, so it stops short of 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 core action, then cleanly sectioned into USE THIS WHEN / NOT FOR / Produces / Args. Every block earns its place, though the per-diagram 'Produces' enumeration partly restates what the output schema already conveys, making it marginally longer than necessary.

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?

A high-complexity, five-parameter tool with 0% schema coverage is fully covered here: purpose, exclusions, parameter formats and defaults, auth/tier constraints, and mode-dependent output. With an output schema present, no return-value detail is owed, and nothing an agent needs 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 must carry the full burden - and it does: three accepted github_url URL formats (repo, tree/branch/dir, blob/branch/file), when to use codebase instead (private repo or files in context), max_nodes default 20 and range 5-50, github_token scope (repo), and report_mode's three-state semantics including omission behavior.

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 (analyse/reverse-engineer) and resource (existing codebase) plus the concrete deliverables (class, sequence, state diagrams, smell flags, intelligence report). The NOT FOR section names four sibling tools, so an agent can distinguish it from umlforge_stakeholder_arch, umlforge_living_docs, umlforge_erd_schema, and umlforge_api_sequence 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?

Explicit USE THIS WHEN list (GitHub URL, audit, need diagrams of existing code) and a NOT FOR list that routes to four named alternatives, each with the condition that selects it. Nothing about when-to-use 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 this is a safe, read-only, non-destructive operation. Beyond that, the description discloses what is actually produced (the four artifact types), states that report_mode requires a Pro/Team/Enterprise plan, and explains the omit-to-use-saved-preference fallback — meaningful context annotations cannot express. It stops short of noting generation latency or cost, which for a multi-diagram generation call would be the remaining useful detail.

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 verb+resource, then sectioned into USE THIS WHEN / NOT FOR / Produces / Args. The NOT FOR lines are one line each and the Args block mirrors the schema order, so nothing is padded.

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 enumerated, yet the Produces section still tells the agent what diagrams come back, letting it judge sufficiency before invoking. Combined with the tri-state report_mode semantics and the tier restriction, an agent has everything needed 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 description coverage is 0%, so the description carries the full burden, and it does: all three parameters are explained, with audience_description illustrated by two examples and report_mode given precise tri-state semantics (True adds notes, False forces diagrams only, omit inherits the dashboard setting) plus its tier gate. system_description's explanation is comparatively thin, which keeps it off a 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) and resource (C4 architecture diagram) with a qualifying scope: a mixed technical/non-technical audience. The explicit NOT FOR list naming umlforge_reverse_engineer, umlforge_api_sequence, umlforge_deployment and umlforge_threat_model makes the boundary against siblings unambiguous.

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 gives three concrete triggering scenarios (stakeholder presentation, high-level planning, wanting Context+Container+Component in one call) and the NOT FOR block routes each adjacent need to a named alternative tool.

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 safety is covered. The description goes beyond them by listing the concrete artifacts produced (stateDiagram-v2 with ERROR/TERMINAL states, transition table, implementation notes) and by flagging that report_mode is Pro/Team/Enterprise only and that omitting it falls back to a saved dashboard preference. It does not mention rate limits or token/latency characteristics, 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 with the one-line purpose, then cleanly sectioned into USE THIS WHEN / NOT FOR / Produces / Args. The Produces block partially duplicates what the output schema would convey, and some bullets are long, but every sentence carries routing or behavioral information 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?

For a 5-param generation tool with an output schema, the description covers purpose, routing to siblings, required vs optional args, and the tier restriction on report_mode. Since an output schema exists it needn't describe return shape, and the brief Produces summary is a bonus rather than a gap. Minor omission: no note on what happens with malformed/incomplete states lists.

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: entity, states, events, and business_rules each get a plain-language gloss with an example, and report_mode's tri-state behavior (True / omit / False) is explained precisely, including the tier gate. This fully compensates for the empty schema titles, though it stops short of format guidance such as whether states/events are comma-separated strings.

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 state machine for a domain entity') and immediately scopes it to entities with a lifecycle. The USE THIS WHEN examples (Order: pending → active → cancelled) make the scope concrete, and the NOT FOR section names three siblings so an agent can route correctly 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 when-to-use bullets with concrete triggers (entity moves through states, need to model approval chains, want to find missing states/race conditions), plus a NOT FOR section that names the exact alternative tool for each excluded case (umlforge_api_sequence, umlforge_event_driven, umlforge_reverse_engineer). 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.

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 genuine context beyond that: it discloses the response contract (tool name, pre-filled parameters, one-line explanation, plus a suggested alternative). It doesn't note the non-idempotent behavior, but that is carried by the annotations.

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 'START HERE' banner and a numbered outcome list, then use-case bullets, examples, and arg guidance — well organized and scannable. There is mild redundancy across the numbered list, the USE THIS WHEN block, and the example inputs, but each section serves a distinct purpose so nothing is pure 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 single-parameter router with an output schema and full annotation coverage, this is complete: an agent knows what it does, when to invoke it, how to phrase the argument, and what the response contains. No relevant invocation detail 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% and the input schema gives only a bare string type, so the description must carry the full burden — and it does. It explains that task_description should contain URLs, entity names, service names, and tech stack, and reinforces this with four concrete example inputs, teaching the agent exactly how to populate the single required parameter.

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 function: given a plain-English goal, identify the right tool, return the exact pre-filled tool call, and explain the choice with an alternative. This clearly distinguishes it from its 14 siblings as the meta-router/dispatcher. An agent immediately knows this is the entry point rather than a domain tool.

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 gives explicit conditions: unsure which tool, wanting a ready-to-run recommendation from a goal, avoiding trial and error. Strong positive guidance, but it never states the inverse (skip this and call the specific tool directly once you know it), so it stops short of full when/when-not coverage.

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, so the safety profile is covered. The description adds non-obvious behavior the annotations do not: report_mode is Pro/Team/Enterprise-only, and omitting it falls back to a saved account preference while False forces diagrams-only. It does not mention latency, size limits, or whether generated artifacts persist, so it stops short of a 5. Generating an artifact under readOnlyHint=true is consistent with "does not mutate the described system" semantics rather than a contradiction.

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?

Headers (USE THIS WHEN, NOT FOR, Produces, Args) front-load routing information and the ordering is logical. The "Produces" block partly restates what the output schema already covers, making it slightly longer than strictly necessary, but nothing is padded or redundant enough to hurt.

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 generative tool with a rich output schema, the description covers routing, exclusions, parameter examples, tier constraints, and default-resolution behavior. An agent has everything needed to select and invoke it correctly without consulting siblings.

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: it documents all six parameters with concrete examples ("JWT Bearer token", ["public internet → API", "API → database"], "NDPA 2023") and marks the four optional ones. It also explains report_mode's tri-state semantics (True / omit / False) and tier gating, which the bare boolean|null schema cannot convey.

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?

StartsWith a specific verb+resource+methodology ("Generate a full STRIDE security threat model for a system"), leaving no ambiguity about what the tool returns. It also explicitly names the sibling tools it is not (umlforge_reverse_engineer, umlforge_deployment, umlforge_api_sequence), so an agent can disambiguate without opening 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?

The USE THIS WHEN / NOT FOR structure gives explicit triggers, explicit exclusions, and a named alternative for each exclusion (e.g. architecture review → umlforge_reverse_engineer with report_mode=True). This is the strongest possible routing guidance.

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