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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, but the description still adds real behavior: what data comes back (type, IaC attributes, all relationship directions) and how fuzzy matching resolves, including returning candidate choices on ambiguity. It does not mention cost or size limits on large relationship sets, which keeps it from 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, front-loaded with the resource scope and return contents, followed by the matching rule. No redundant or filler wording.

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

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

With only two required, fully documented parameters and no output schema, the description supplies the missing return-shape information (type, attributes, relationships) plus the ambiguity path. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema description coverage is 100%, so the schema already defines both graphId and resource, and the description's 'id, name, or substring' largely restates the schema entry. Its only addition is the ambiguity-resolution outcome, which is a modest gain over the structured data.

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 ('Describe') on a specific resource ('one resource in an ArcSync diagram') and enumerates exactly what is returned: type, IaC attributes, and inbound/outbound relationships. Scope ('one resource') implicitly separates it from whole-diagram siblings like get_diagram, though no sibling is named.

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?

When-to-use is only implied by the singular-resource scope; it never says to prefer get_diagram for a full diagram or get_diagram_source for raw source. The one explicit procedural hint is about ambiguous matches returning candidates, which is useful but is a result-handling rule rather than tool-selection 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 read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds real substance: the result is a set of resources added, removed and changed, and the comparison baseline shifts depending on `version`/`against`. The PR-branch prerequisite is noted but the failure mode for a non-PR diagram is not.

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 compact sentences, front-loaded with the core purpose, then branching cleanly into the no-version and with-version cases. No filler or redundancy.

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

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

With no output schema, the description carries the burden of conveying the return shape, and it does so at a useful level (added/removed/changed resources). For a three-parameter read tool this is nearly complete; only the non-PR-branch edge case is unaddressed.

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 only 33%, and the schema documents only `graphId`. The description compensates by defining `version` as a timestamp obtained from list_versions and clarifying that `against` only matters when `version` is set, with 'live' meaning the latest parse. The 'previous' enum value is left to inference as the implied default.

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 and resource: 'Show what changed in a diagram's infrastructure,' with the two operating modes spelled out. It is implicitly distinguishable from siblings like get_diagram or list_versions by being a comparison operation, 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?

Clear contextual routing: omit `version` for a PR-branch delta, supply `version` (sourced from list_versions) to compare against the preceding version, or set `against` to 'live' for the latest parse. It stops short of stating what happens when `version` is omitted on a non-PR-branch diagram or when to prefer get_diagram 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 cover readOnly, idempotent, non-destructive and open-world, so the bar is low; the description still adds substantive behavior — what each format returns, that mermaid is the default, and that both responses include an interactive-canvas link. It does not describe error behavior for an unknown graphId.

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

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

Three tight sentences, front-loaded with the purpose, then format semantics, then the routing hint. Every clause carries information an agent would otherwise have to guess.

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 carries the return-value burden by describing both response shapes and the canvas link. Only minor gaps remain, such as failure behavior for a missing or stale graphId.

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

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

Schema coverage is 50%: graphId is documented in the schema, but the format enum has no description there. The description compensates by naming both enum values, declaring mermaid the default, and explaining what each yields — real meaning beyond the schema.

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

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

States a specific verb and resource with scope: "Fetch one architecture diagram ArcSync parsed from infrastructure-as-code." An agent knows exactly what it gets. It stops short of differentiating from the closest sibling, get_diagram_source, which also sounds like a way to obtain a diagram's content.

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 clear usage context with "Prefer this to inferring architecture from source files" and prescribes which format to pick for display versus reasoning. It names no exclusions and never says when to use get_diagram_source or get_delta instead, leaving the main sibling ambiguity unresolved.

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. The description adds one genuine constraint — only diagrams authored via push_diagram have retrievable source — but says nothing about failure behavior for unknown or non-authored graphIds.

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 resource and round-trip purpose front-loaded, followed by the ID provenance. No redundant or filler wording.

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

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

For a single-parameter read tool with full annotations and no output schema, the description covers what is returned (source text) and where the ID comes from. Minor absence of error-case guidance keeps it from a 5.

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

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

Schema coverage is 100% and the graphId parameter already documents that it is the value returned by push_diagram. The description restates that same fact rather than adding new meaning (e.g., acceptable ID forms or reuse across versions), so the baseline 3 applies.

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?

Names a specific verb and resource ('Return the stored ArcSync source text of an authored diagram') and scopes it to diagrams created via push_diagram. It implicitly separates itself from get_diagram by emphasizing 'source text', but never names that sibling to make the distinction explicit.

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?

Describes a clear workflow context: use it to retrieve source, edit it, and push again, with the graphId coming from push_diagram. There are no explicit exclusions or named alternatives (e.g., when to use get_diagram instead), which keeps it short of a 5.

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; the description adds real value by disclosing the return payload (status, current phase, percentage, error on failure) and the accepted id forms. It does not mention whether completed/failed are terminal or how often to poll, which is the remaining behavioral gap.

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

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

Two sentences with zero filler; the action and its linkage to start_parse come first, followed by the returned fields. Every clause carries information an agent needs to call and interpret the tool.

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

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

For a single-parameter, read-only polling tool with no output schema, the description adequately encodes the response shape and id semantics. The only shortfall is operational guidance on polling behavior and terminal states, which is minor given the annotations cover the safety profile.

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 100%, so the baseline is 3, but the description adds lifecycle meaning the schema does not: a completed parse reports a canonical graphId that can then be passed back in. That clarifies why two identifier forms are accepted, beyond the schema's bare statement that 'the id start_parse returned also works'.

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

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

States a specific verb+resource ('Report the progress of a parse') and explicitly scopes it to parses started with start_parse, which cleanly separates it from the sibling start_parse. It even enumerates the status values, so an agent knows exactly what this returns.

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?

Names the pairing explicitly ('a parse started with start_parse') and tells the agent which identifier form to supply, which effectively implies when to call it (after a parse is initiated). It stops short of stating polling cadence or what to do when status is terminal, so it is clear context but not full when/when-not guidance.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds real context beyond them: results are scoped to the caller's workspace, deduplicated per repo/branch/path, and sorted newest first. It does not mention pagination beyond the limit cap or total counts, which is the remaining behavioral gap.

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

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

Two sentences, zero filler. The ordering and scope constraint is front-loaded, and the workflow pointer follows immediately after.

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-param, zero-required list tool with no output schema, the description supplies the key return field (graphId), ordering, and filtering semantics. It could say more about what each row contains beyond graphId, but nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns an extra point by enumerating what `query` matches against (repository URL, owner, repo name, branch, path, project type) and confirming substring-style filtering. `limit` is left entirely to the schema, which already documents its default and maximum.

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 ("List the architecture diagrams"), plus scope ("caller's ArcSync workspace"), cardinality ("one per repository, branch and IaC path") and ordering ("newest first"). The list_versions sibling is about versions rather than diagrams, so the resource distinction is legible without opening a schema.

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

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

Gives an explicit downstream workflow: use this to obtain a graphId before calling get_diagram, describe_resource or get_delta. It lacks an explicit when-not or a contrast with list_versions/list_icons, so it stops short of full routing guidance.

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

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

Annotations already declare this as read-only, idempotent, open-world, and non-destructive. Beyond those, the description adds useful behavioral context by saying results are grouped by vendor and that `query` filters by substring, though it does not discuss pagination or ordering within groups.

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 compact examples and no redundant wording. Every clause contributes to identifying the resource, its usage, and its return grouping.

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 listing tool with one optional parameter and no output schema, the description is complete enough: it explains the resource, shows valid example ids, states grouping, and documents the filter. No critical agent need 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?

The schema has 100% description coverage and already says `query` is a case-insensitive substring. The description restates that it filters by substring without adding new syntax, defaults, or edge-case behavior, so the baseline of 3 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 and resource: 'List the icon ids a diagram node can use' in the `@{ icon: "..." }` expression. It gives concrete examples (aws:lambda, azure:function-apps, gcp:cloud-storage) and states the grouping, so the agent can immediately tell this apart from diagram/source/version tools.

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 intended use is clear: discover icon ids for use inside a diagram node expression, with `query` available to narrow results. It does not state when not to use the tool or name alternatives, but the use case is explicit enough for selection.

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 genuinely new behavior: result ordering (newest first), granularity (one version per re-parse), included metadata, and a plan-entitlement restriction (Pro feature) that could cause an otherwise valid call to fail. Pagination or result-count limits are not mentioned, 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?

Three compact sentences, with the core behavior and result shape front-loaded and the sibling handoff immediately after. Every clause carries information — ordering, granularity, returned metadata, next-step routing, and entitlement caveat — 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?

There is no output schema, so the description must convey return content; it does so by naming the commit origin and change magnitude and by specifying newest-first ordering. Combined with the annotations, an agent has enough to call it correctly. Minor omissions are pagination behavior and any cap on the number of versions returned.

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

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

Schema description coverage is 100% and the single graphId parameter is already well documented, including where to obtain the value, in the schema itself. The description adds no input-parameter meaning; its reference to `timestamp` concerns an output field consumed by get_delta rather than an input. Baseline 3 applies when the schema carries this load.

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 the saved versions of a diagram") and qualifies the result set with meaningful scope: one entry per re-parse, newest first. It even names the payload fields (originating commit and change magnitude), which lets an agent distinguish this from siblings like get_diagram_source or get_delta without inspecting schemas.

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

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

It explicitly routes the agent forward: "Pass a version's `timestamp` to get_delta to see what it changed," which names the alternative and the condition selecting it. It also surfaces the Pro-feature prerequisite, an important gating condition. It stops short of stating when not to call it (e.g., when version history is unavailable on the current plan, or for the current working state).

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 mark this as a non-read-only, non-destructive, open-world write. The description adds substantial context beyond annotations: private visibility, update-on-same-id semantics, returned canvas and embed links, quota consumption, and the required pre-validation step.

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 core action, then covers update semantics, return values, and limits in a compact sequence. Every clause carries operational information and there is 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?

For a write/update tool with no output schema and full parameter coverage, the description supplies the key missing context: validation prerequisite, visibility, quota impact, and return links. It does not describe failure or error behavior, but is otherwise complete 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 coverage is 100%, so source, title, and diagramId formats are already documented in the input schema. The description adds meaningful behavior for diagramId by explaining that re-pushing it updates the existing diagram, but adds little parameter-specific detail for title or source beyond the schema.

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

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

States a specific verb and resource: validate and store an ArcSync diagram as a private diagram in the caller's workspace. It also distinguishes create-vs-update behavior via diagramId and names validate_diagram as the prerequisite, so an agent can tell it apart from read-only siblings.

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?

Explicitly says to call validate_diagram first and explains that pushing the same diagramId updates the existing diagram. It also warns that calls count against workspace diagram and hourly limits, though it does not give a direct when-not-to-use or named alternative beyond the validation 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 only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false; the description adds the async contract (returns a graphId at once), quota consumption per call, extra server-side synthesis for CDK and Pulumi, and the private-repo auth prerequisite. These are real operational costs an agent cannot infer from structured fields, and they are consistent with the non-idempotent, non-destructive annotations.

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

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

Three sentences, no filler, with the purpose front-loaded and the cost/workflow caveats following. The long parenthetical format list and chained clauses in the first sentence make it slightly dense, but every sentence 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 an asynchronous, quota-consuming creation tool with no output schema, the description explains what is returned immediately (graphId), how to follow up, and the preconditions around quota and repository access. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so repoUrl, path, and branch are already documented in the schema, and the description adds no further parameter-level detail such as URL validation behavior or how path interacts with monorepo layouts. A baseline 3 is appropriate when the schema carries the parameter burden.

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 ('clone a GitHub repository and parse its infrastructure-as-code ... into a diagram') and enumerates the supported IaC formats. It is immediately distinguishable from siblings like list_diagrams and get_diagram, which consume rather than create diagrams.

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

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

Gives an explicit ordered workflow: poll get_parse_status until complete, then call get_diagram. It also names a when-not condition — call list_diagrams first and reuse an existing diagram — plus the constraint that private repositories require the ArcSync GitHub App.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuine value by disclosing the return shapes: "OK with node and edge counts" versus "INVALID with one line per problem (block:line:column, and a suggestion when one exists)." It stops short of saying whether any files or state are touched on disk, but the "locally, without pushing it" phrasing covers the main concern.

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 core action and the non-pushing constraint, followed by a short next-step instruction. No filler or redundancy.

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

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

With no output schema, the description carries the burden of explaining results and does so precisely (OK counts vs. INVALID per-error lines with location and suggestion). For a single-parameter, read-only validation tool, nothing an agent needs to call it correctly is missing.

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

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

There is only one parameter and the schema already documents it at 100% coverage, including the ```arcsync fence and Mermaid/@{} metadata syntax. The description restates the same fence concept without adding format or size guidance, so the baseline 3 applies.

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 concrete verb ("Check") and resource ("ArcSync diagram source (```arcsync blocks)") and immediately scopes it as local validation "without pushing it," which cleanly separates it from push_diagram and the parse/delta siblings.

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

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

It gives an explicit workflow: run validate_diagram, fix every error, then call push_diagram. The alternative (pushing) is named along with the condition that selects validation first, so no inference is required.

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