Moretes Architect MCP

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no restatement, and the output schema covers return values. The description adds that the plan is derived deterministically from explicit capabilities and risks, but says nothing about determinism of recommendations, depth/verbosity of the plan, or limits on the scenarios it can cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that packs the verb, resource and deliverable list with no filler. Slightly dense in its comma-list form but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with five required parameters, an object array, and an output schema, the description covers the overall intent but leaves the agent guessing what 'agent' and 'tools' should contain and how much detail to supply. Adequate to call, but not complete.

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, yet it only touches two of five inputs (capabilities, risks) plus an oblique nod to releaseCadence via 'regression cadence'. The 'agent' identifier and especially the 'tools' array with its {name, mutating} shape — a materially important input for red-team and guardrail design — are never 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 ('design') and resource ('evaluation plan for an AI agent') and enumerates the five deliverables (golden set sizing, metrics, judge rubric, red-team cases, regression cadence), so an agent knows exactly what it gets. It does not, however, name or contrast any sibling such as agent_tool_contract or prompt_injection_checklist, which overlap in the agent/red-team space.

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?

'from explicit capabilities and risks' implies the caller must supply capabilities and risks as inputs, which is weak usage guidance. There is no statement of when to prefer this over agent_tool_contract, prompt_injection_checklist, or implementation_plan, and no exclusions or prerequisites.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, and the description is consistent with them (a design/advice operation), so there is no contradiction. However, the description adds no behavioral context of its own — nothing about whether output is deterministic for identical inputs, whether it validates or critiques an existing contract, or any constraints beyond the 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though the efficiency comes partly from omitting rather than compressing necessary detail.

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?

The presence of an output schema means return values need not be explained, which the description correctly leaves out. But for a tool with five mandatory, undescribed inputs and no usage routing, the definition is thin — it never says what the resulting contract contains or how the inputs shape it, leaving the agent to guess at semantics.

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 five required parameters, so the description carries the full burden and largely fails: 'per-operation' faintly hints at 'operation', 'authorization' at 'approvalRequired', and 'recovery' at 'reversible', but 'resourceScope' (array of strings, up to 30 items) and 'maxDurationSeconds' (1–3600) get no explanation at all. An agent cannot tell what a valid scope entry looks like or how the duration bound should be chosen.

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 ('Design') and a specific artifact ('per-operation authorization and recovery contract for an agent tool'), which is distinguishable from siblings such as agent_eval_plan or implementation_plan. The word 'contract' is left abstract, so the agent gets the category but not the shape of the deliverable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to reach for this tool versus agent_eval_plan, implementation_plan, or threat_model, and no prerequisites or exclusions are given. The agent must infer timing entirely from the one-line purpose.

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/idempotent/non-destructive/closed-world, and the description adds real context: it discloses that each persona returns its own questions, checks, deliverables and recommended workbench tools, and that the output is perspective rather than a verdict. That framing materially shapes how an agent should consume and present results. It stops short of describing cost, latency, or determinism for multi-persona invocation.

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?

One dense sentence with the action front-loaded and the payoff clause trailing; nothing is redundant. The parenthetical persona list is long but earns its place by defining the roles enum, though it slightly buries the 'Lens, not a verdict' qualifier at the end.

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-value detail is not required, and the description covers what the panel produces. But for a 4-required-parameter tool with 0% schema coverage, the absence of any guidance on artifactType and knownFacts leaves a real gap an agent would have to guess through.

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 4 required parameters. The description explains the roles dimension by enumerating all ten personas, and 'on a subject' maps loosely to the subject param. However artifactType (an 8-value required enum) and knownFacts (the array that presumably grounds the panel) get no explanation at all, leaving half the required inputs semantically opaque.

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 ('Convene architect personas ... on a subject') and enumerates the persona set, so an agent knows exactly what the tool produces. It also signals the output shape (questions, checks, deliverables, tool calls) and the advisory framing ('Lens, not a verdict'). It does not explicitly differentiate itself from related review siblings like well_architected_review or threat_model.

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?

Usage is implied by 'on a subject' and the 'lens, not a verdict' caveat, which tells the agent this is advisory rather than a decision tool. There is no explicit when-to-use/when-not guidance and no named alternative among the many review-oriented siblings, so routing still requires 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, idempotent, closed-world, non-destructive behavior, so the safety profile is covered. The description adds genuinely non-obvious behavior: labels are sanitized (input may be altered in the output) and dangling edges are rejected (hard validation failure rather than silent dropping). It does not mention the node/edge count caps (40/80) that will also cause failures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the core action front-loaded before the behavioral caveats. Nothing here could be cut without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is unnecessary, and annotations cover the safety profile. Still missing for a structured-input builder: the cardinality limits, the id format constraint, and what 'sanitizes labels' actually does to a label (strip characters? truncate?). An agent can probably call it correctly but may hit avoidable validation errors.

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, and it does partially: it frames the two parameters as nodes and edges and conveys that edge endpoints must reference existing nodes ('rejects dangling edges') and that labels are sanitized. However, it says nothing about the node id pattern (^[a-zA-Z][a-zA-Z0-9_]{0,39}$), the 40-node/80-edge maximums, or that edge labels are optional and length-capped.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Build Mermaid from explicit nodes and edges'), so the agent immediately knows this produces a diagram artifact from a node/edge graph rather than prose or a pattern recommendation. It implicitly distinguishes itself from sequence_diagram and c4_model by requiring an explicit graph input, but never names those siblings to make the contrast 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?

There is no statement of when to reach for this tool versus sequence_diagram, c4_model, or architecture_pattern, all of which are plausibly adjacent in the sibling list. The only guidance is an input-shape precondition ('from explicit nodes and edges'), which tells the agent what to supply, not when to select this 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds that output contains tradeoffs, questions and a Mermaid diagram, and that provider remaps AWS services to other clouds. It does not explain what 'questions' means concretely or whether pattern coverage is exhaustive, but for a read-only lookup this is solid added context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and the primary selector; no filler. The second sentence is slightly compressed to the point of being terse, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape need not be spelled out (the description does anyway). However, with 0% schema coverage and a mandatory free-text workload parameter left undefined, the definition does not fully equip an agent to invoke it 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%, so the description must compensate. It clarifies pattern ('explicit workload pattern') and gives provider real semantics ('maps the AWS services to Azure, GCP, OCI or open source equivalents'), but the required 'workload' string (up to 4000 chars) is never explained — the largest gap, since an agent cannot tell whether it wants a name, a narrative, or constraints.

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?

A specific verb and resource ('Select a reference architecture') scoped by 'explicit workload pattern', plus a note that the result includes tradeoffs, questions and Mermaid. It is distinguishable from diagram-oriented siblings like architecture_diagram or c4_model, though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'By explicit workload pattern' implies the tool is used when a workload maps to a known pattern, and the enum of patterns reinforces that. There is no statement of when NOT to use it, no prerequisites, and no pointer to siblings such as architect_panel or service_equivalents that overlap with provider mapping.

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, idempotent, and openWorld, so the safety profile is covered. The description adds genuinely non-obvious context beyond them: the URL is fixed upstream and arbitrary fetching is not permitted, which tells the agent where valid inputs come from. It omits any mention of truncation or paging behavior, which matters for a long-document reader.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the usage trigger front-loaded ahead of the URL-provenance constraint. Every clause earns its place.

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?

The tool is a read-only fetch with no output schema, so the description does not need to explain return values, and the URL constraint is well communicated. However, with three required, undocumented parameters and no explanation of how chunked reading works, an agent cannot reliably page through a long document.

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 parameter burden, and it documents only the url indirectly ('no arbitrary URL fetch'). startIndex and maxLength are never mentioned; an agent has no cue that they page through a long document in chunks of up to 12000 characters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource (read an official document) and scopes it to documents 'returned by search', which distinguishes it from aws_knowledge_search. It stops short of saying what 'read' actually returns (a slice of the document), leaving the retrieval semantics implicit.

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?

'Read ... when its excerpt is insufficient' gives a clear trigger condition and implies the two-step search-then-read workflow without naming the sibling explicitly. There is no statement of when not to use it or what to do if the URL is not from search results.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description's real addition is the egress disclosure that queries are transmitted to AWS Knowledge and must not contain secrets or customer data — useful context beyond openWorldHint. It stops short of describing result freshness, rate limits, or failure modes for an external network call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with purpose and immediately followed by the safety constraint. Nothing is padded and every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and zero parameter documentation, the description should carry the burden for a three-required-parameter tool dominated by a ten-value enum, but it does not. An agent still cannot tell what a result looks like or which `topic` value to choose for a given question.

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 three required parameters. The description adds nothing about `topic`, which has ten enum values (general, reference_documentation, cdk_constructs, strands_docs, etc.) whose selection meaning is entirely undisclosed, and nothing about `query` phrasing or the `limit` cap of 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 and resource ("Search live official AWS documentation"), which clearly separates it from synthesis-style siblings like well_architected_review or architecture_pattern. It does not explicitly distinguish itself from the closely related aws_knowledge_read sibling, leaving the search-vs-read boundary to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence is a data-handling constraint, not usage guidance: it never says when to pick this over aws_knowledge_read, aws_skill, or aws_regional_availability. No prerequisites, no exclusions, no indication of when live docs are preferred over cached/regional data.

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, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavioral context — that filter names come from a catalog and can be discovered by omitting them — but says nothing about pagination behavior despite a nextToken parameter, nor about result freshness or cost of a lookup.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero filler, and the core purpose is front-loaded before the filter hint. The brevity is efficient rather than padded, though it borders on under-specified.

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?

Four parameters with 0% schema description coverage, a pagination token, a three-value enum and no output schema — the description is far too thin for this surface. An agent still cannot tell what resourceType values mean, whether multiple regions are batched, or how to continue past a page.

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 and it largely does not. It explains filters (exact catalog names, omittable) but leaves regions, resourceType (what product/api/cfn actually select) and nextToken/pagination completely undefined; the enum values and the multi-region semantics are left to guesswork.

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?

"Check current regional support" gives a verb and a resource area, but never states what is supported (a product, API, or CloudFormation resource per the resourceType enum) or what is returned. Critically, it does not distinguish itself from the sibling aws_regions tool, which reads like a near-synonym to an agent choosing between them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence gives one real usage rule: omit filters when querying a single region to discover valid filter names. That is useful guidance but is scoped entirely to the filters parameter; there is no statement of when to use this tool instead of aws_regions or aws_knowledge_search, and no exclusions.

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 this as a read-only, idempotent, open-world operation, so the safety profile is covered. The description adds useful context that the source is the official Knowledge MCP and that results are current, but it does not describe return format or any other behavioral traits.

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?

The description is a single, front-loaded sentence with no wasted words. Every part of the sentence contributes to identifying the resource and its source.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple parameterless list tool with annotations covering safety, the description is nearly complete. It could clarify whether the output is a bare list of region codes, but no output schema exists and the core operation is clear.

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?

The tool has zero parameters, so there is no parameter semantics to document. The baseline for a parameterless tool is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List current AWS regions', plus the source ('official Knowledge MCP'). It is clear what the tool returns, but it does not explicitly differentiate from the sibling tool 'aws_regional_availability'.

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 gives no explicit guidance on when to use this tool versus alternatives such as 'aws_regional_availability' or 'aws_knowledge_read'. It only implies usage through its purpose statement.

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, idempotent, non-destructive, open-world behavior, so the safety profile is covered. "Treat it as reference data" usefully signals that returned content is informational rather than instructions (a prompt-injection cue), but nothing is said about result size, pagination, or what the `file` selector does.

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?

One compact sentence plus a short directive, with the key selection constraint front-loaded. Nothing is wasted or repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with no output schema, the core usage story is present, but the undocumented `file` parameter and the absence of any expectation about returned content leave an agent guessing on non-default calls.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description only indirectly covers `skillName` ("exact ID"). The optional `file` parameter is left completely unexplained in both schema and description, which is a real gap for a retrieval tool where an agent must decide whether to pass it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Retrieve an official AWS skill") and names the exact provenance of the key ("the exact ID returned by aws_knowledge_search with agent_skills topic"). That clearly separates it from the sibling search/read tools an agent might otherwise pick.

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 implies the workflow (search first with the agent_skills topic, then retrieve by the returned ID) and tells the agent how to treat the result ("reference data"). It does not explicitly say when to prefer aws_knowledge_read or what happens if the ID is wrong, so no explicit exclusions.

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 read-only, idempotent, non-destructive, closed-world behavior, so the description is not carrying the safety burden. It adds real behavioral context beyond them: endpoints are validated, and the tool does not perform infrastructure discovery. Missing are what happens on validation failure and whether output is returned as text or file.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and artifact, then the constraint. No filler, nothing repeated from the schema.

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, and annotations cover safety. However, with 6 required parameters and a level enum, the description omits how the two levels differ in required model content — a meaningful gap for correct invocation.

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?

With 0% schema description coverage the description must compensate; it names the entity categories (people, systems, containers, relations) and implies the level choice, plus 'validates endpoints' hints that relation from/to must reference declared ids. It does not explain the id pattern, the maxItems caps (15 people / 30 containers / 80 relations), or which collections apply at context vs container level.

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 artifact: builds C4 context or container diagrams in Mermaid from explicit people, systems, containers and relations. That specificity separates it from generic siblings like architecture_diagram or sequence_diagram, though it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'From explicit ... no infrastructure discovery' implies the caller must supply the full model rather than expect discovery, which is useful usage context. But there is no explicit when-to-use-this-vs-architecture_diagram or sequence_diagram guidance, and no prerequisites stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds real value with the disclaimer 'No service sizing guarantee', telling the agent the output is arithmetic, not a provisioning recommendation. It does not state determinism, rounding, or unit conventions, so it stays at a solid but not rich 3.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with what is computed, followed by the one caveat that matters. No filler, no restatement of the tool name, and the qualifier is placed where it will be read before calling.

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 no explanation, and annotations carry the safety profile. But for a pure-calculation tool the critical missing piece is what the inputs mean and in what units, and with 0% schema coverage the description leaves all four required parameters undefined, including the non-obvious headroom multiplier.

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 all four parameters are required, yet the description never names or explains any of them. 'Traffic assumptions' gestures vaguely at requestsPerSecond and payloadKB, but the meaning of headroom (a 1.0-10.0 multiplier defaulting to 1.3) and the units/limits of durationMs are left entirely to inference.

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 (Calculate) and two specific outputs (concurrency and daily data volume) plus the input class (explicit traffic assumptions). It implicitly separates itself from siblings like storage_growth or latency_budget, though it never names a sibling to sharpen the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use, when-not-to-use, or named alternative. The phrase 'from explicit traffic assumptions' hints that the caller must supply measured or assumed traffic rather than deriving it, but an agent has to infer that, and nothing says when capacity_plan should be chosen over queue_sizing, latency_budget, or cost_model.

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 (readOnly, non-destructive, idempotent), and the description adds real value beyond them: 'selected' patterns signals partial coverage, and the note that intrinsic functions are flagged for human review rather than resolved is an important behavioral limitation. It stops short of saying what happens to unrecognized resources or how findings are presented.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The purpose is front-loaded and the intrinsic-function caveat follows immediately after, so every clause earns its place.

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, and annotations carry the safety story. What remains thin is the definition of 'selected risky patterns' — an agent cannot predict which findings it will get — but the description is otherwise sufficient to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it partially does: 'CloudFormation JSON template' tells the agent the parameter is the template body itself (an object), not a YAML string or S3 URL. It adds nothing about the shape of that object or what key patterns are inspected, leaving the single required parameter thinly specified.

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 (Review) and resource (CloudFormation JSON template) with defined scope ('selected risky configuration patterns'). The resource type alone separates it from terraform_plan_review, kubernetes_manifest_review and iam_policy_review in the sibling list, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the verb 'review' — an agent can infer this is a static pre-deployment check on a template. There is no explicit statement of when to reach for this versus the other *_review siblings, and no prerequisites or exclusions.

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 read-only, idempotent, non-destructive, closed-world, so the safety profile needs no restatement. The description adds the traits annotations cannot capture: results are heuristic (not authoritative), scope is pasted text only, and the output is advisory rather than a scanner substitute. It stops short of saying what a finding looks like or that very large files are capped, but with an output schema present that omission is minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the operation and scope, followed by a dense but readable checklist. The one-word qualifier 'Heuristic' in the lead position correctly sets expectations early. Slight cost: the inline enumeration reads as a run-on, though no sentence 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?

Given an output schema that explains the return value and annotations that cover safety, the description supplies the missing essentials: input must be pasted text, any language is accepted, and findings are heuristic. The remaining gap is the language/filename parameters and the input size limit, which an agent with a large file could get wrong.

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 load, and it only partially does: 'pasted as text' clarifies that code is a literal string body (not a path or URL) and 'any language' gestures at the language enum. Neither filename nor the auto-detection behavior of language='auto' is mentioned, and the 60,000-character cap goes unstated.

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?

Specific verb (scan) plus resource (source code pasted as text), with an enumerated checklist of what is detected (secrets, insecure calls, concatenated SQL, disabled TLS, hardcoded endpoints, timeouts, retry hazards). No sibling covers pasted-code security scanning — the closest ones (dependency_manifest_review, cloudformation_review, mcp_config_review) target other artifacts, so the tool is distinguishable 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?

'Not a linter or SAST replacement' is an explicit exclusion that tells the agent when the result is insufficient. However, no positive trigger is given (e.g., use this before cloudformation_review / iam_policy_review, or when no repo access is available), and no alternatives are named 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered structurally. The description adds the genuinely useful trait that it will not fabricate prices or credit coverage, but says nothing about how contingency is applied or what the calculation produces.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core mechanism stated first and the negative guardrail second. Nothing repeats the tool name or title.

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, and annotations cover the safety profile. The remaining gap is the unexplained contingencyPercent and item limits, which an agent would need before constructing a valid call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden and only partially delivers: 'unit rates' maps to pricePerUnit and 'source URLs' to source. The required contingencyPercent, currency enum (USD/BRL), quantity, unit, priceDate, and the 50-item cap are all left unexplained, and contingencyPercent materially drives the result.

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 ('Calculate') and object ('auditable scenario') and pins down the mechanism: caller-supplied unit rates and source URLs. The negative clause ('Does not guess AWS prices') usefully separates it from pricing-lookup siblings like finops_unit_economics, though 'auditable scenario' remains slightly abstract as a resource name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'caller-supplied' and 'does not guess AWS prices' phrasing implies the condition for use — you already have rates and sources — but it never states when to call this versus finops_unit_economics or aws_knowledge_search, nor any prerequisites beyond supplying inputs.

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, idempotent and non-destructive, so the safety profile is covered. The description adds real value by enumerating what the output contains (regulation hints, handling controls, open questions) and flagging the legal-advice limitation, which is behavioral context an agent would otherwise have to infer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and outputs, and the legal-advice caveat earns its place as a risk boundary. No 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?

The output schema covers return values and annotations cover safety, so the description mainly owes parameter guidance — which it omits entirely for a tool with three required parameters and a nested object array. Adequate on intent, incomplete on how to supply inputs.

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 description says nothing about `system`, `elements` (a nested structure requiring name/category/purpose/sharedWith), or `jurisdictions` (BR/EU/US/other). The regulation names hint at jurisdictions but never map them to the parameter or its codes, leaving the heaviest parameters undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (classify) plus the resources and outputs (regulation hints for LGPD/GDPR/PCI DSS/HIPAA, handling controls, open questions). It is clearly distinct from advisory siblings like threat_model or well_architected_review, but it doesn't explicitly name what it is not.

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?

Usage is implied (run it against a system's data elements with target jurisdictions), and 'Review aid, not legal advice' sets expectations about its authority. However, there is no explicit when-to-use/when-not guidance and no named alternative among the many review-oriented siblings.

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/idempotent/non-destructive, so the safety profile is covered. The description adds one meaningful behavioral fact — it will not infer an "accepted" status, the caller must supply it — which is real context beyond the annotations. It says nothing, however, about whether the ADR is persisted, returned inline, or what happens when status is omitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero padding, and the primary action is front-loaded before the caveat. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be described, and the ADR framing is recognizable. But for a six-parameter, all-required tool at 0% schema coverage, the description should explain the status enum and the options minimum, which it does not — an agent can only infer them from property names.

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, yet it only gestures at three of six parameters (options as "alternatives", decision, consequences) without explaining formats or limits. It never mentions title, context, or status (the only enum), and omits the structural rules the schema enforces — options require 2-10 entries, consequences up to 30.

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 a specific artifact ("an ADR") plus the inputs it is built from, so the tool's function is immediately clear. It does not name or contrast any sibling, but among the review/plan tools none is close enough to be confusable, so differentiation is implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this versus alternatives (e.g. implementation_plan, architecture_pattern) and no prerequisites or exclusions. "Does not invent acceptance" is a constraint on inputs, not usage routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value by signaling the analysis is performed on the manifest 'as text' (i.e., pure static analysis of supplied content, not a fetch from a repo) and by listing the categories of findings it produces.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single well-formed sentence, front-loaded with the verb and resource, with the file-type list in parentheses so it does not interrupt the main clause. Nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape need not be described, and annotations cover the safety profile. However, for a three-parameter tool with zero schema coverage, the description leaves gaps that matter to correct invocation: the format/role of filename, how lockfilePresent interacts with the 'missing lockfile hints' check, and what happens with an unrecognized manifest type.

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 there are three parameters, so the description must compensate. It only weakly does: 'as text' hints at the content parameter and 'missing lockfile hints' vaguely gestures at lockfilePresent, but neither is explained — the reader cannot tell whether that flag is self-reported or checked by the tool. The filename parameter (whether it is a basename, path, or used for format detection) is never addressed.

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 (Review) and resource (dependency manifest) and enumerates the concrete file types it handles (package.json, requirements.txt, go.mod, etc.), which immediately distinguishes it from sibling reviewers like openapi_review or cloudformation_review. It also names the exact defect classes it looks for: unpinned ranges, git/URL sources, wildcard versions, missing lockfile hints.

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?

Usage is only implied by the file-type list — an agent can infer 'use this when you have a dependency manifest as text,' but there is no explicit when-to-use, when-not-to-use, or named alternative (it does not, for example, differentiate itself from the sibling requirements_check).

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful caveat beyond that: the output is 'feasible tiers and required capabilities, not a guarantee' — framing the result as advisory rather than prescriptive. It stops short of describing how feasibility is judged or how ties are broken.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence that front-loads the action, the four tiers, the evaluation criteria, and the output caveat. Every clause earns its place with no 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 and annotations cover the safety profile, so return values do not need explaining. But with seven required-ish inputs at 0% schema description coverage, the description leaves half the inputs semantically opaque, which is a meaningful gap for a planning tool whose accuracy depends on those inputs.

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 seven parameters, so the description carries the full burden, yet it only obliquely references rtoMinutes, rpoMinutes, and dataGB. Four parameters — workload, statefulComponents, regulatoryResidency, replicationBandwidthMbps — are never mentioned, and no units, formats, or significance are given for the ones it does hint at.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Compare') and resource ('disaster recovery tiers') and enumerates the four candidate tiers, plus the criteria used (RTO, RPO, data constraints). No sibling tool covers DR strategy, so the agent can distinguish this from architecture_pattern, capacity_plan, etc. on domain 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?

Usage is implied by the purpose: an agent would call this when selecting a DR tier for a workload given recovery objectives. However, there is no explicit 'use when' condition, no prerequisite guidance (e.g. must have RTO/RPO defined first), and no reference to alternatives or follow-on tools like runbook or failure_rehearsal.

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, idempotent, non-destructive, closed-world. The description adds real value beyond them: 'Deterministic template with open questions' tells the agent the output is a reusable template that may surface unresolved items rather than a final decision. It does not discuss output format, but an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the core action and scope; the template/determinism note is placed at the end as a secondary qualifier. No wasted text.

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?

Behavioral context is adequate and an output schema covers returns, but with 6 required parameters and zero schema descriptions, the description leaves the agent without guidance on what to supply for producer, consumers, payloadFields, or the enum choices.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description adds no per-parameter meaning. It mentions 'named business event' (loosely eventName) and ordering, but does not explain producer, consumers, payloadFields structure, or the ordering/deliveryGuarantee enums, leaving the agent dependent on bare schema field names.

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?

Specific verb ('Design') and resource ('event contract') plus an enumerated scope: envelope fields, schema evolution, idempotency, ordering, DLQ, replay. An agent can distinguish it from delete/update style tools, though it does not explicitly contrast itself with adjacent design tools like retry_policy or integration_config.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for a named business event' and the listed decision areas imply when it applies, but there is no explicit when-to-use/when-not guidance and no named alternative for overlapping design tasks (e.g., sequence_diagram, integration_config).

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/destructive=false/idempotent, and 'never executes it' reinforces rather than contradicts them. The description adds genuine behavioral context about the artifact's shape (success criteria and stop conditions must be present), though it says nothing about output format or constraints on generated drills.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded clause carrying the verb, the resource, the required design qualities, and the execution boundary. Nothing is wasted and nothing is buried.

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?

The output schema exists, so return values needn't be explained, and the non-execution boundary is covered. But with three required, undescribed parameters and no guidance on how the drill content relates to 'operation'/'target', the definition is only minimally sufficient for correct invocation.

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?

Three required parameters with 0% schema description coverage, and the description never mentions any of them. 'operation' and 'target' are undefined in both places — an agent must guess whether operation is a command, an API call, or a described workflow — and the failure enum meanings are only inferable from their names.

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 controlled failure drill') plus the key attributes (observable success criteria, stop conditions) and an important boundary. It is clear what the tool produces, but it never names a sibling (runbook, dr_strategy, postmortem) to differentiate itself from adjacent artifacts.

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?

'never executes it' is an explicit exclusion that tells the agent not to expect an actual drill run, which is a real usage boundary. However, there is no positive statement of when to reach for this versus runbook or dr_strategy, so the routing guidance is partial.

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, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds a real behavioral trait beyond them: it is a pure local calculator that does no price lookups or guessing, which tells the agent results are fully determined by its inputs and repeatable. It stops short of describing output shape, but an output schema exists for that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, with the computed outputs front-loaded and the input-provenance caveat placed last. Every clause contributes information the schema does not already state.

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?

The output schema relieves the description of explaining return values, and the input-provenance note covers determinism. But for a 6-parameter tool with zero schema descriptions, gaps remain: the 'primary unit' concept in targetCostPerPrimaryUnit is undefined, and period/currency semantics are left entirely to the 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 must carry the parameter burden, and it partially does: units (request/customer/transaction) map to the units array, and the fixed-vs-variable split and 'target' map to fixedCosts, variableCosts and targetCostPerPrimaryUnit. It does not clarify what period means, nor which entry in units is the 'primary unit' that targetCostPerPrimaryUnit is measured against, leaving genuine ambiguity.

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 (compute) with three named outputs: cost per unit, fixed-vs-variable split, and the volume where marginal cost crosses a target. That is far more specific than a tautology, but it never names the sibling it should be chosen over (e.g. cost_model or capacity_plan), so an agent still has to infer the boundary from the last clause.

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?

"Caller supplies costs; no provider prices are guessed" is a usable selection signal: use this when you already have your own cost inputs rather than when you want priced AWS services. However, no when-not condition or alternative tool is named, so the guidance remains implied rather than explicit.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new context beyond the annotations: a fixed api.github.com destination and no token/auth requirement, which tells the agent this works unauthenticated against a known host.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the scope constraint front-loaded and zero filler. 'Contribution links' is slightly vague, but the sentence still earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read-only tool with full annotations, the description covers scope, host, auth, and result kind ('metadata and contribution links'). With no output schema, slightly more detail on what metadata fields are returned would help, but nothing essential to invoking 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 coverage is 0%, so the description must compensate, and it says nothing about `owner` or `repo`. The names are largely self-explanatory, which keeps this at minimum-viable rather than failing, but there is no guidance on format (case sensitivity, max length, or that they form an owner/repo pair).

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: reads public GitHub repository metadata and contribution links. The 'public' qualifier distinguishes it from any private-repo sibling, though none exists among the sibling tools, so no further differentiation is required.

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?

Implies usage (fetching metadata for a public repo) and includes an implicit exclusion ('no private repositories'), but does not state when an agent should reach for this versus other tools or note any prerequisites beyond 'public'.

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, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description contributes one genuinely useful trait beyond them — that results are heuristic and superseded by provider analyzers — but says nothing about handling of malformed input, partial coverage, or confidence levels.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and scope, then the format mapping, then the caveat. Nothing is repeated from annotations or the schema and 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?

With only two required parameters and an output schema that carries the return structure, the description covers what an agent needs to build a valid call. The remaining gap is minor: no note on what happens if the supplied document does not match the declared provider format.

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, and it does: it maps the `provider` enum values to the concrete document shapes expected in `policy` (AWS policy JSON, Azure role definition, GCP IAM bindings). It stops short of describing required keys inside each format, which keeps it from 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 and resource ('Inspect an IAM document for broad grants') and enumerates the three accepted document formats, which is enough to separate it from review siblings like cloudformation_review or terraform_plan_review. It does not explicitly name those siblings as alternatives, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The default provider (AWS) and the accepted per-provider formats imply when the tool applies, and 'the provider analyzers are authoritative' hints that this is a first-pass check. However, there is no explicit statement of when to reach for this versus a deeper review tool, nor any exclusion or prerequisite.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds only a hint about output shape ('validation gates'), which the output schema already carries — no disclosure of limits, failure modes, or what the checklist guarantees.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. Its brevity costs specification rather than being wasteful, but as structure it is clean.

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 covers return values, but the description says nothing about the two required inputs or when the tool applies, so an agent must guess at argument content and at how this differs from planning 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% for two required parameters. The description never explains what a 'decision' string should contain (a slug, prose, a reference ID?) nor the granularity expected of 'deliverables' (max 30 items). With zero schema documentation, the description needed to compensate and does not.

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 transformation (architecture decision -> delivery checklist with validation gates), which is a recognizable verb+resource and is distinguishable from siblings like decision_record or migration_plan. It falls short of 5 because it never mentions the two inputs that define the operation, leaving the scope slightly abstract.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus decision_record, migration_plan, or requirements_check — all plausible neighbors in the sibling list. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds two useful facts beyond that—results come from a fixed snapshot and are metadata only, not runnable tools—but says nothing about snapshot freshness or result shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler, and the core action is front-loaded. The second sentence is terse enough to be slightly cryptic rather than wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema and rich annotations reduce the burden, so the definition is close to sufficient. Still, for a search tool the conventions of the query string and the stale-snapshot caveat are exactly what an agent needs and are only half-addressed.

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 and does not. Neither 'query' (matching semantics, empty-string default) nor 'limit' (max 70, default 20) is explained, leaving an agent to guess whether query is free text, name prefix, or filter syntax.

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: 'Search the snapshot of the complete official AWS MCP catalog.' That distinguishes it from review-oriented siblings like mcp_config_review and from aws_knowledge_search, though the 'snapshot' framing is left undefined.

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?

Usage is only implied by the noun 'catalog' and the caveat that discovery entries are not hosted/executed tools. There is no explicit statement of when to reach for this over mcp_server_review or aws_knowledge_search, and no exclusion 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, idempotentHint=true and non-destructive, so safety is covered. The description adds the useful exclusion of install/start/approve side effects, which reinforces behavior beyond annotations. It does not describe the generated artifact form or whether it's returned inline vs written to disk, so with annotations present a 3 fits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence plus a negative clause; no filler. Front-loads the two output modes before the exclusion, which is the right order.

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?

The output schema presumably documents the return shape, and annotations give the safety profile, so the remaining gap is parameters and the branch condition distinguishing the AWS-server config from the remote Knowledge config. For a 3-required-param generator with two modes, the description leaves too much unstated.

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 all three parameters are required, so the description carries the full burden. It never mentions serverId, awsProfile or region, nor their formats, defaults or the difference between the local-AWS path and the remote Knowledge path. Anonymous params make correct invocation harder.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States the resource (a version-pinned local config for an official AWS server, or a remote Knowledge config) but the verb is fuzzy: 'Generate' doesn't say what artifact or output is produced beyond 'configuration'. Sibling tools like integration_catalog and mcp_config_review are adjacent, and nothing distinguishes this tool from them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The negative scope ('Does not install, start or approve tools') gives an implied when-not, but there's no explicit when-to-use or comparison against integration_catalog or mcp_config_review. An agent must infer selection from sibling names alone.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuinely new behavioral fact — 'No cluster access' — telling the agent no credentials, live state, or fetch step are involved, which changes how the agent prepares input. It stops short of describing output shape or severity, but an output schema exists to carry that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler. The checklist is front-loaded and each enumerated item maps to a real check the tool performs, while the scoping constraint ('No cluster access') is placed last as a clean boundary statement.

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, return values need not be explained, and the annotations cover the safety profile. The remaining gap is audience guidance — e.g. which resource kinds are recognized and whether multi-document/bundle-wide checks (PDB and NetworkPolicy coverage) require all related manifests in a single call, which the agent must infer.

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 load; it partially does by specifying 'parsed JSON objects', which disambiguates from raw YAML strings — the most likely caller error. It says nothing about the array bound (maxItems 300) or that a single-element array is valid, leaving the coverage gap only half closed.

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?

Uses a specific verb ('Review') with a specific resource ('Kubernetes manifests') and enumerates exactly what is inspected: probes, resources, security context, image pinning, host access, secrets in env, PDB and NetworkPolicy coverage. The Kubernetes-manifest domain cleanly separates it from sibling review tools like terraform_plan_review, cloudformation_review and iam_policy_review.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'No cluster access' usefully bounds the tool to static analysis of supplied objects, implying the caller must provide the manifests rather than a cluster reference. However, it never states when to prefer a different review tool, whether it applies to Helm/Kustomize output or only rendered manifests, or what prerequisites the input must satisfy.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description earns some credit by confirming the tool does no external lookups ("pure arithmetic" / "caller-supplied"), which reassures the agent results are deterministic and offline. It omits anything about the 30-hop cap, how parallelGroup affects the arithmetic, or what a hop 'share' actually means.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core action front-loaded and the execution model (pure arithmetic) as a compact qualifier. Nothing here is restated from annotations or schema.

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. But for a tool whose whole value depends on interpreting hop fields correctly, the description leaves parallelGroup and cacheable unexplained and gives no hint about how the percentile choice affects the split. Adequate to identify the tool, not adequate to invoke it optimally.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, yet it explains none of targetMs, percentile, or the hop fields. Critically, cacheable and parallelGroup are semantics-bearing fields whose effect on the budget split is completely undocumented, and an agent cannot guess how caching discounts a hop's share.

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 ("split an end-to-end latency objective across hops") plus the secondary output ("show which hops exceed their share"). The line "Pure arithmetic over caller-supplied estimates" sharply distinguishes it from data-fetching siblings, but it never names the closest alternative, slo_budget, so the boundary is left for the agent to infer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase "caller-supplied estimates" implies the precondition that the agent must already have per-hop numbers, and that this is an analysis step rather than a measurement step. However there is no explicit when-to-use, no when-not-to-use, and no routing to slo_budget or capacity_plan, which is the most likely confusion point.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety burden is covered. The description adds real value beyond that by naming the specific risk categories inspected (unpinned packages, inline secrets, plain HTTP, auto-approved tools, unreviewed enablement), which tells the agent what kind of findings to expect.

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?

One front-loaded sentence with the verb first and a tight parenthetical clarifying the resource shape. Every clause carries 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?

With annotations covering the safety profile and an output schema presumably describing the findings, the description only needs to explain scope and intent, which it does. The only gap is the ambiguous input format for `config`, which matters given the untyped 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% and the single `config` parameter is an untyped object, so the description must compensate. The parenthetical '(mcpServers map)' does hint at the expected shape, but it does not clarify whether the input is a parsed object or a raw JSON string, nor what keys are meaningful.

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 (Review) and resource (MCP client configuration JSON), and enumerates the exact classes of issues it looks for. It is clear what the tool does, but it never distinguishes itself from the sibling mcp_server_review, which an agent could easily confuse it with.

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 enumerated checks imply when the tool is useful (auditing an mcpServers config), but there is no explicit when-to-use/when-not guidance and no pointer to mcp_server_review or other siblings for adjacent tasks. Usability is inferred rather than directed.

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, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description still adds value by labeling the analysis 'heuristic' (i.e., non-authoritative findings) and by disclosing the exact threat surface it inspects, which goes beyond what the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences: the scope and input source come first, then the checklist of inspected artifacts. No filler, and the enumerated checks are compact enough to scan without 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?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. What remains thin is the mapping between the two required parameters and the pasted payload, plus any note on the 300-tool cap, but the description is sufficient to invoke the tool 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 the load. 'Paste the JSON your client shows' meaningfully clarifies that the tools array should be raw tools/list output, but the required serverName parameter is only obliquely implied by 'ANOTHER MCP server' and is never defined.

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 ('safety review of ANOTHER MCP server from its tools/list output') and enumerates the six checks performed, so an agent knows exactly what it produces. The phrase 'ANOTHER MCP server' and 'from its tools/list output' distinguish it from the sibling mcp_config_review, which operates on config rather than a live tools/list dump.

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?

'Paste the JSON your client shows' gives a concrete input instruction, and 'ANOTHER MCP server' implies it is not for self-review. However, it never names when to prefer it over mcp_config_review, prompt_injection_checklist, or other review siblings, leaving the routing decision 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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds some behavioral context by naming the phased gates and AWS Transform integration discovery, but it does not clarify that this is advisory planning rather than execution or explain input requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact sentence with no wasted words, but that concision comes at the cost of under-specification. It is not front-loaded with the essential purpose or parameter context an agent needs.

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?

The tool has four required parameters with no schema descriptions, yet the description provides no parameter explanations or usage guidance. An output schema exists, so return values need not be described, but the input side and tool selection guidance are materially incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not mention source, target, strategy, or constraints at all. With four required parameters and no parameter-level documentation in either the schema or the description, an agent receives no semantic guidance for invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a verb ('Prepare') and lists migration phases/gates (discovery, pilot, migration, rollback), which gives a rough idea of purpose. However, it never explicitly says it produces a migration plan, and it gives no differentiation from siblings like implementation_plan or architecture_pattern.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool, when not to use it, or which sibling tools are alternatives. The agent must infer usage entirely from the name and sparse description.

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 the safe read-only, idempotent, closed-world profile, so the description only needs to add what they cannot. Calling the review 'heuristic' meaningfully signals that findings are judgment-based and non-exhaustive rather than a deterministic ruleset, and the enumerated check areas tell the agent what kind of findings to expect. Return shape is covered by the output schema, so nothing critical is missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, with the scope and the covered dimensions front-loaded and the disambiguation clause placed last where it reads as a caveat. Every phrase earns its place.

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 one parameter, full annotation coverage and an output schema, the description gives the agent enough to call it correctly: what to pass and what the analysis covers. The only gap is that document size limits or handling of non-3.x specs is left implicit in '3.x' rather than stated.

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, and it does contribute the essential constraint: the input is an OpenAPI 3.x document in JSON form. It does not clarify whether the caller passes a parsed object versus a serialized string (the schema implies an object with arbitrary properties), nor whether Swagger 2.0 is rejected. Adequate compensation, but not full.

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 ('Heuristic review of an OpenAPI 3.x document (JSON)') and enumerates the exact dimensions checked: security, pagination, error responses, idempotency, versioning, documentation gaps. The closing clause distinguishes it from linters, so an agent can place it against the sibling *_review family 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?

The negative guidance is explicit ('Not a linter replacement'), which tells the agent when to prefer a spec-linter instead. However, there is no positive trigger — no statement of when an agent should reach for this over siblings like mcp_server_review or cloudformation_review, and no prerequisites such as document size or supported versions beyond '3.x'.

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 carry the safety profile (readOnlyHint=true, idempotent, non-destructive), so credit goes to what the description adds beyond them: the explicit failure mode 'rejects action items without owner and due date' and the required document sections. It stops short of saying whether the document is persisted or returned, which is the one behavioral question left open.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the core artifact description is front-loaded ahead of the validation constraint. Every clause conveys information the agent cannot get from the schema.

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?

The output schema means return values need no explanation, and annotations cover safety, but this is an 11-required-parameter, fully nested-array tool with a 0%-described schema. Missing guidance on timestamp ordering (started ≤ detected ≤ mitigated ≤ resolved), severity semantics, and array size expectations leaves the definition thin for the tool's complexity.

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 11 required parameters, so the description has to carry the load. It does map to several fields (impact, timeline, contributing factors, action items) and flags the owner/due-date requirement, but never mentions title, severity levels, the four incident timestamps, whatWentWell, or the action-item 'kind' enum, leaving over half the surface undocumented in prose.

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 artifact ('generate a blameless postmortem document') and enumerates exactly what it is built from: timeline, impact, detection, contributing factors and owned action items. That framing cleanly separates it from adjacent siblings such as runbook or decision_record, which produce different artifacts from different inputs.

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?

Usage is only implied: the input set (startedAt, detectedAt, mitigatedAt, resolvedAt) signals 'call this after an incident is resolved.' No explicit when-to-use, when-not-to-use, or named alternative is given, so the agent must infer prerequisites such as whether the incident must be fully closed before a postmortem can be generated.

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, idempotentHint=true, destructiveHint=false and a closed-world scope, so safety is covered. The description adds genuine value beyond them by disclosing the output's nature: a partially-filled checklist template, not an automated scan — which sets correct expectations for the agent consuming the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence, front-loaded with the action and scope, with the disambiguating 'not a scan' clause placed at the end where it is still visible. Nothing is padded, though the dense phrasing packs several ideas into one clause chain.

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 explained, and the safety profile is in annotations. But with four required, undocumented parameters (including a structured tools array and a fixed enum of untrusted source types), the description leaves the agent to infer input shapes it should really be told.

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 four required parameters, so the description must carry the burden. It only gestures at two of them conceptually ('tools and untrusted data sources') and says nothing about the agent name, humanInLoop, or the critical per-tool 'mutating'/'external' flags that drive the checklist's contents.

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 (enumerate) and resource (injection paths and controls) scoped to an agent's tools and untrusted data sources, and the trailing clause clarifies the artifact is a checklist rather than a scanner. It doesn't name the adjacent sibling threat_model, so differentiation is only partial, but the purpose itself is 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 phrase 'produces a checklist with status to fill, not a scan' implicitly tells the agent when NOT to reach for this (i.e., when an automated scan is wanted), which is useful. However, no alternative tool is named and no prerequisites or context for when this belongs in a workflow (e.g., pre-deployment review vs. threat_model) are given.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds that this is a pure analytical calculation based on named queueing models, which helps set expectations for deterministic output. However, it says nothing about validity conditions (e.g. that arrival rate times service time must be below capacity, or how an unstable/overloaded queue is reported) — a meaningful omission for a sizing calculator.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence that front-loads the core action and then enumerates the returned metrics. No filler and appropriately sized for a calculator tool, though the clause list is slightly run-on.

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 no explanation, and annotations cover the safety profile. But with six required, zero-documented parameters and no statement of the model's preconditions or interpretation of results (e.g. what a wait probability near 1 implies), the definition is only marginally sufficient for correct invocation.

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 six required parameters, so the description must carry the explanatory burden and it does not. It never clarifies units (serviceTimeMs is implied by the name), what maxConcurrencyPerConsumer actually means, or how backlogMessages interacts with drain-time output. The output list loosely maps to targetUtilizationPercent and backlogMessages, but several parameters remain semantically opaque.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Size consumers for a queue') and the modeling technique (Little's law, Erlang C), so an agent knows exactly what computation this performs. It also enumerates the computed outputs (utilization, wait probability, backlog drain time, consumers needed), which is more specific than most siblings. It does not explicitly contrast itself with capacity_plan or slo_budget, keeping it at a 4.

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?

Usage is only implied: the listed inputs and outputs (arrivals, service time, backlog, target utilization) sketch the scenario where the tool applies, but there is no explicit 'use this when' statement, no exclusions, and no mention of capacity_plan or latency_budget as alternatives. An agent can infer the context but must guess at boundaries.

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, idempotentHint, openWorldHint=false and destructiveHint=false, so the agent knows this is a deterministic pure-computation call. The description adds moderate context beyond that: the plan surfaces 'open questions' and deliberately stops short of vendor selection, which tells the agent not to expect a concrete product recommendation. It says nothing about depth, determinism guarantees, or how assumptions are handled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler; the resource and its coverage areas come first, and the scope caveat lands last where it belongs.

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?

The output schema covers return values, so the description needn't explain them, and annotations cover the safety profile. However, for a tool requiring five structured inputs including a nested corpus object with enums, the total absence of parameter semantics leaves the definition under-specified for correct invocation.

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 5 required params plus a nested corpus object with 5 sub-fields, so the description carries the full explanatory burden and largely fails. 'Authorization' maps to one parameter, but useCase, latencyBudgetMs, citationsRequired, and every corpus sub-field (documents, averagePages, formats, updateFrequency, languages) go entirely unexplained — no guidance on how they change the output.

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?

Specific verb + resource: 'Plan a retrieval-augmented generation pipeline', and it enumerates the exact facets the plan covers (chunking, embedding, indexing, authorization, evaluation, cost drivers). The RAG-specific framing plus 'No vendor is chosen for you' distinguishes it from the generic planners in the sibling list such as implementation_plan or architecture_pattern.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'from corpus facts' implies prerequisite inputs and 'No vendor is chosen for you' rules out vendor selection, so usage is implied. But there is no explicit when-to-use vs. when-not guidance and no routing to alternatives such as implementation_plan or architecture_pattern for follow-on 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?

The annotations already cover the safety profile (read-only, idempotent, closed-world, non-destructive), so the bar is lower. The description still adds a real behavioral constraint — it will not invent SLAs or budgets — which tells the agent what the tool deliberately omits. It says nothing about depth or limits of the analysis, which keeps it at 4 rather than 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action, no filler. The exclusion clause is placed where it does the most work.

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?

The tool has an output schema and rich annotations, so return values and safety are covered elsewhere. However, with three required inputs at 0% schema description coverage and no parameter guidance in the description, an agent cannot confidently populate requirements and constraints. This is the main completeness gap.

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 three required parameters, so the description must compensate and does not. 'Workload brief' only loosely hints at the workload string; it says nothing about what belongs in requirements versus constraints, how the two arrays differ, or how they interact.

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?

It names a specific transformation (workload brief → explicit requirements, gaps, research questions) and draws a boundary ('no inferred SLA or budget') that separates it from slo_budget and capacity_plan. It stops short of 5 because the resource is described only in abstract nouns, and it never names a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The exclusion clause 'No inferred SLA or budget' implies an alternative exists for those concerns, which is useful routing. But there is no explicit 'use this when…' statement and no named alternative, so the agent must infer when to pick this over capacity_plan or slo_budget.

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, idempotentHint, closed-world and non-destructive, and the word 'Compute' is consistent with that safe, pure-calculation profile. The description adds that the output includes deadline-fit analysis and circuit-breaker guidance, which goes slightly beyond the annotations, but says nothing about determinism, limits, or how the guidance is derived.

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?

One sentence, front-loaded with the core action and resource, with the secondary outputs trailing. No filler or repetition.

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 explained, but for a 7-parameter computation with zero schema descriptions and required inputs like operationIdempotent and jitter mode, the definition leaves too much to inference. A brief note on what each knob controls (and that operationIdempotent changes the guidance, not the schedule) would close the gap.

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 7 parameters (6 required), so the description carries the full burden — yet it explains none of them. baseDelayMs, factor, capMs, maxAttempts, the 'none'/'full'/'equal' jitter enum, deadlineMs and operationIdempotent (which drives the guidance output) are all left for the agent to guess from names alone.

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 ('Compute an exponential backoff schedule with jitter') and enumerates the concrete outputs: worst-case wait, deadline fit, plus idempotency and circuit-breaker guidance. That clearly separates it from every sibling, which are review/plan/document generators rather than a backoff calculator.

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 purpose implies when it is useful (sizing retries for an unreliable dependency), but there is no explicit when-to-use, when-not-to-use, or named alternative among siblings. An agent must infer the triggering situation from the one-sentence purpose.

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 read-only, idempotent, non-destructive, so safety needs no restating. The description adds genuinely new behavior: missing inputs become explicit placeholders rather than being invented, which resolves the ambiguity of 8 required params where several arrays carry defaults.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the core action plus section list is front-loaded ahead of the placeholder caveat.

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 structure need not be explained, and the placeholder rule covers the main behavioral unknown. The remaining gap is that nothing says how the caller should shape alert objects or whether step arrays are ordered.

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 names alerts, diagnostics, remediation, rollback, escalation, but omits service, owner and dashboards, and introduces 'verification' which is not a parameter. It maps most inputs to output sections but gives no guidance on item format or ordering.

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 artifact ('Generate an operational runbook') and enumerates the sections it will contain, so an agent knows exactly what it gets back. It does not name which sibling to prefer (postmortem, failure_rehearsal, dr_strategy), so differentiation is left to the reader.

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?

'from service facts' implies the caller must supply the operational details, and the placeholder behavior hints at how to handle gaps. But there is no explicit when-to-use versus a sibling like postmortem or dr_strategy, and no statement of prerequisites.

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 (readOnly, idempotent, non-destructive, closed-world), so the description only needed to add context beyond that — and it does, by disclosing that output is Mermaid source and that unknown participants cause rejection. It omits the size ceilings (60 messages, 15 participants) and any error shape, 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?

Two sentences, capability front-loaded, optional features second, validation caveat last. No filler or restatement 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?

An output schema exists, so return formatting needn't be described, and the enums/patterns in the input schema are self-explanatory. The description covers purpose, core inputs, and optional constructs, but for a schema this intricate with zero property descriptions, the review-block semantics (else/end) and style variants are left to inference.

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 semantics, and it partially does: it maps participants, ordered messages, activation, notes and blocks to concepts. It never mentions the required 'title', the sync/async/reply style enum, or the actor/participant kind, leaving several required fields explained only by their enum values.

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 artifact ('Build a Mermaid sequence diagram'), names the exact inputs (participants and ordered messages), and enumerates optional features (activation, notes, alt/loop blocks). An agent can distinguish it from architecture_diagram or c4_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?

Usage is only implied by the artifact type — nothing states when to pick this over the diagram-adjacent siblings (architecture_diagram, c4_model) or when not to. 'Rejects unknown participants' is a validation rule, not selection guidance.

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