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

Annotations declare readOnlyHint=false and openWorldHint=false, so the agent knows this is a side-effecting but self-contained operation; the description adds real value by disclosing what edges are derived from and what is invisible (application-code-only calls). However it omits where rendered files land, what happens when render_diagram is false, and whether inputs are mutated, which are non-obvious side effects for a tool flagged as not read-only.

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

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

Front-loads the one-line purpose, then input acquisition, then layout/edge derivation, then filtering and the known limitation, so an agent can stop reading early. The embedded shell command and layout hierarchy string add density but each earns its place as actionable input prep.

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?

Covers input sourcing, topology hierarchy, edge inference, filtering, and the follow-up workflow, which is a lot for a 12-parameter tool with no output schema. Still missing: where output artifacts are written, default output format behavior, and what the returned spec looks like when rendering is skipped, which an agent needs to chain correctly into generate_architecture_diagram.

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

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

Schema description coverage is 0%, so the description carries the full burden and does substantial work: it explains inventory_json vs path, the projects/regions/labels filters with a concrete labels example, and include_neighbors behavior. Five parameters (provider, direction, output_formats, render_diagram, include_kubernetes, title) are left entirely to their self-explanatory names, which is a modest but real gap.

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

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

States a specific verb (diagram), a specific resource (already-running infrastructure), and the source of truth (the cloud's own inventory with real names), which separates it conceptually from the Terraform-based sibling. It never names diagram_from_terraform explicitly, so the agent must infer the boundary between the two, which keeps it 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?

Gives concrete input instructions (the exact gcloud asset list/export command, or a file path within configured input roots) and explains the filter semantics plus include_neighbors. It also routes the agent forward with 'add those edges to the returned spec and re-render with generate_architecture_diagram' when app-code-only calls are missing, though it never states when to prefer diagram_from_terraform instead.

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 is non-readOnly, non-idempotent, non-destructive and closed-world, so the safety bar is low. The description still adds real behavior: VPC/VNet/subnet/resource-group map to nested boundaries, references become edges, and dashed edges mean inferred relationships via listeners/NICs/role assignments. It also states the return value (the generated spec, refinable and re-renderable), which annotations cannot 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?

Three tight lines: purpose first, then how to supply input, then the mapping behavior and return value. Every sentence carries information and 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 no output schema, the description correctly states what is returned. It also covers the complex part (resource-to-boundary mapping) plus the input-root security constraint. It falls short on the remaining parameters — notably the required title and the render_diagram toggle — which an agent must infer from the schema alone.

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

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

Schema description coverage is 0%, so the description must compensate. It does add genuine meaning for terraform_json (accepts raw JSON text) and path (must be inside configured input roots), but says nothing about title, direction, output_formats, or render_diagram — four of six parameters, including the only required one, are unexplained.

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

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

The description opens with a specific verb+resource ('Build a diagram from Terraform') and enumerates the exact input artifacts it accepts (plan JSON, state JSON, .tfstate). It implicitly separates itself from diagram_from_inventory by naming Terraform as the source, but never names that sibling, so the differentiation is only partial.

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?

'Pass the JSON text in terraform_json, or a file path inside the configured input roots' gives useful guidance on which of the two source parameters to use. However, there is no statement of when to prefer this over diagram_from_inventory, nor any exclusions or prerequisites for the tool as a whole.

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 destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds value by defining the return contract ('file paths and an inline PNG preview') and noting that SVG output is self-contained. It omits where files are written and whether output persists, which is a real gap for a tool that writes to disk.

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?

Six tight lines, each covering one spec field, with the verb front-loaded and no qualifying boilerplate. Nothing needs to be cut.

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 description states the return values, which matters because no output schema exists, and it explains the structure of the nested spec. The only omissions are the presentation-level options (theme, direction, curve_style, filename), which have defaults and schema-level enums.

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?

Top-level schema coverage is 0%, so the description must compensate, and it does so for the four principal fields: it explains that clusters represent boundaries (accounts, regions, VNets/subnets, AZs, namespaces), that edges are node-to-node, and that nodes map to icon ids. However, it never mentions theme, direction, curve_style, filename, or title, so the documentation covers only part of the spec.

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

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

The first line gives a specific verb and resource: 'Render an architecture diagram with official provider icons.' It also routes to search_icons for icon ids. It does not distinguish itself from diagram_from_terraform or diagram_from_inventory, which also produce diagrams, so it falls 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?

Usage is implied rather than stated: 'type = icon id from search_icons' signals a two-step flow, but the description never says when to use this tool instead of diagram_from_terraform or validate_diagram, or whether validating first is recommended.

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 openWorldHint=false, so the safety profile is covered. The description adds the useful behavioural detail that the returned spec is meant to be modified before use, but says nothing about spec size, format, or whether the returned object is a scaffold with placeholders. With annotations carrying the safety burden, this is an adequate but thin addition.

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 return value and followed by the intended use. Nothing is padded or restated from the name 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-value detail is legitimately omitted, and the read-only annotations cover safety. The critical gap is the required template_id: with zero schema coverage and no mention of list_templates as the source of IDs, an agent lacks what it needs to invoke the tool correctly on the first try.

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

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

Schema description coverage is 0% for the single required parameter template_id, so the description carries the full burden and must compensate — and it does not. It never says where template_id comes from (presumably list_templates) or what form it takes, leaving the agent to guess how to obtain a valid value.

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 ("Return a reference architecture spec") and ties it to its downstream consumer, generate_architecture_diagram, so it is distinguishable from that sibling. It does not explicitly differentiate itself from list_templates, which is the more likely confusion point for an agent hunting for templates.

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 clear workflow context: fetch a spec, customise it, then pass it to generate_architecture_diagram. That tells the agent when this tool belongs in a sequence. It stops short of naming alternatives or stating when not to use it (e.g. when you already have a spec, or to browse templates use list_templates).

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 closed-world behavior, so safety is covered. The description adds that the result spans all categories and includes the icons within each, but says nothing about ordering, volume, or shape beyond 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?

One front-loaded sentence with zero filler; the scope ('every category') and returned content ('service icons in each') are packed efficiently.

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

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

For a simple, read-only, one-enum-parameter listing tool with an output schema, the description is nearly sufficient. The only missing piece is routing guidance against search_icons, which the output schema and annotations cannot supply.

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%, but the single parameter is a self-explanatory provider enum. The description only signals that the value selects a provider; it adds no nuance about enum values or defaults (though the parameter is required).

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 every category of a provider and the service icons in each'), making the tool's function immediately clear. It does not explicitly contrast with the sibling search_icons, but the browse-everything framing distinguishes it in practice.

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: 'every category' suggests a browse-all/discovery use case versus filtered search, but the description never names search_icons or states when to prefer one over the other. No prerequisites or exclusions 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 readOnlyHint, idempotentHint, and closed-world behavior, so the safety profile is covered. The description adds only the existence of bundled templates and their link to get_template; it says nothing about ordering, whether all templates are returned when no filter is given, or how the provider filter narrows results. With annotations carrying the behavioral load, 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 front-loaded sentence with no filler or redundancy. It is efficient, though its brevity comes at the cost of the provider coverage gap noted above.

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 annotations cover safety. What is missing is the provider filter's behavior and the full set of valid categories; for a simple one-parameter list tool this is adequate but leaves a real gap an agent would hit immediately.

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%: the single 'provider' parameter has no description and no separate enum field in the coverage count, so semantics rest on the schema alone. The description compensates only partially and inaccurately, naming three providers when eight are valid, so an agent could wrongly assume k8s/onprem/saas/programming/generic are unsupported or that the argument is optional-by-default with no filtering behavior 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?

Specific verb (List) plus resource (bundled reference architectures), and it names the sibling get_template used to load one. That distinguishes it from get_template and from generation siblings. Minor deduction: the parenthetical '(AWS, Azure, GCP)' understates the actual provider set, since the schema also allows k8s, onprem, saas, programming, and generic.

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 'that can be loaded with get_template' implies a discovery-then-load workflow, which is useful routing. But there is no explicit when-to-use/when-not guidance, and no mention of what to do with the provider filter versus listing everything.

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 closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses the review is heuristic, that findings are bounded by diagram content, and what the output contains (score, grade, recommendations).

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 the core purpose front-loaded and the return contract second; nothing is padding. Minor formatting noise from the mid-sentence line break, but information density is high.

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 spelled out, and the review dimensions are listed. However, given the deeply nested DiagramSpec input, the description never signals the input's shape or required fields, leaving a gap for the caller.

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?

Only one parameter (spec) and the description only refers to it obliquely as "a spec". With reported schema description coverage at 0%, the description does not compensate by explaining that a full DiagramSpec with nodes/edges/clusters is required, so an agent must open the schema to build a valid call.

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

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

States a specific verb and resource ("Heuristic Well-Architected review of a spec") and names the four review dimensions plus the return shape (score, grade, findings). It does not explicitly differentiate itself from validate_diagram, which is the closest sibling and a plausible confusion point.

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 caveat "Findings reflect only what the diagram shows" gives useful context about what the review can and cannot see, but there is no statement of when to choose this over validate_diagram or after generate_architecture_diagram. Usage is implied rather than prescribed.

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 closed-world behavior, so safety is covered. The description adds genuine context beyond them: the ~1,900 icon corpus and the fact that results include canonical ids plus aliases. It stays silent on result count, the limit default, and how provider filtering interacts with the query, which leaves meaningful behavioral gaps.

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

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

Three tight sentences: capability and corpus size first, concrete query examples second, return-value contract last. Every sentence carries information an agent needs, and nothing is padded.

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

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

An output schema exists, so the brief return-value note is sufficient, and the search tool itself is simple. However, with zero schema description coverage the description should have covered the provider filter and the limit/default page size, which it does not.

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 all three parameters. The description explains the query parameter well through examples and the name/alias/category breakdown, but the provider enum (aws, azure, gcp, k8s, etc.) and the limit parameter (default 25) are never mentioned, so two of three parameters remain undocumented anywhere.

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 ('Search ... official icons') plus the searchable fields (service name, alias, category) and the corpus size. It does not explicitly distinguish itself from the sibling list_icon_categories or list_templates, so the differentiation is left to inference rather than stated.

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

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

The example queries imply how to use the tool, but there is no explicit guidance on when to search versus calling list_icon_categories to browse, and no statement of what happens when a query returns nothing. Usage is implied 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=true, idempotentHint=true and openWorldHint=false, so the safety profile is clear. The description adds the categories of information returned, but does not disclose additional behavioral traits such as whether the report includes sensitive identity details, whether any limits are dynamic, or how the report is structured beyond what the output schema covers.

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 filler. Every listed item maps to a concrete piece of reported 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 an output schema present, the description does not need to explain return values. It is complete enough for an agent to understand that this is a parameterless server diagnostics tool.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline score of 4 is appropriate.

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 uses a specific verb ('Report') and enumerates exactly what is reported: version, Graphviz status, icon count, storage, auth mode, caller identity and limits. This clearly distinguishes it from the sibling tools, which all manipulate diagrams, icons, or templates.

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 diagnostic purpose is strongly implied by the enumerated server metadata, so an agent can infer it is for checking server status. However, there is no explicit guidance on when to use it, when not to use it, or whether any alternative exists.

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 read-only, idempotent, closed-world semantics, so the description's job is to say what actually happens. It does: the check covers icon ids (with suggestions), references, nesting, and limits, which tells the agent the validation is deep and non-mutating rather than a shallow schema check.

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, no filler, with the most decisive constraint ('without rendering') placed early. Every clause maps to a distinct check category.

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 annotations cover safety. However, for a validation tool operating on a deeply nested diagram spec with many constraints, the description leaves open whether the tool returns only errors, also suggestions/repairs, and whether a valid spec can then be fed to the generator unchanged.

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?

There is a single top-level parameter 'spec' with no description (0% top-level coverage), though the nested DiagramSpec/$defs fields carry their own rich descriptions. The description adds scope information about which aspects of the spec are validated ('references, nesting, limits'), but does not clarify the shape of the argument itself or whether an invalid spec still needs to be structurally valid.

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 a spec without rendering' names a specific verb (check/validate) and resource (diagram spec), and the 'without rendering' clause implicitly distinguishes it from generate_architecture_diagram. It stops short of naming the sibling explicitly, so an agent must infer the pairing.

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 'without rendering' implies this is the dry-run/pre-flight step before generation, but the description never states when to call it, whether it should precede generate_architecture_diagram, or what to do with a failing result. Usage is implied rather than prescribed.

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