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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the mutation/safety profile is covered. The description adds that it returns created metadata with an assigned id, but says nothing about auth requirements, side effects, or what happens on duplicate names.

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 short and front-loads the core action in the first sentence, with the Args block adding useful detail. The boilerplate Args formatting and the README pointer are mild filler but nothing is padded.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a tool whose main argument is a large free-form blueprint payload, delegating the essential structure to an external README leaves the description incomplete for an agent that cannot open it.

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% at the top level, so the description must compensate, and it does: it defines both required params, explaining 'name' as a display name and enumerating the contents of the 'data' payload (nodes, edges, groups, surfaces, text, icons, connectors, theme, projection). It stops short of detailing payload syntax, deferring to the README.

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 ('Create a new Cloudcraft blueprint'), which cleanly separates it from the list/get/update/delete siblings. It does not, however, explicitly name or contrast itself with those 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?

There is no statement of when to use create_blueprint versus update_blueprint or any other sibling, and no prerequisites or preconditions. The only guidance is 'See README for a minimal example,' which is a pointer rather than usable instruction.

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=true and readOnlyHint=false, so the safety profile is partly covered. The description adds genuinely new context: the operation is irreversible and requires a deliberate second exact-UUID confirmation, which is a behavioral protocol the annotations do not 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?

The destructive action and its confirmation requirement are front-loaded in the first sentence, followed by only two tight argument lines. Every sentence 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?

With an output schema present, return values need not be explained, and the description covers both parameters, the irreversible nature of the call, and the confirmation protocol. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does document both parameters meaningfully: blueprint_id as the target UUID and confirm_blueprint_id as a repeated exact UUID acknowledging irreversibility. It compensates for the schema gap, though it adds no format or validation detail beyond 'UUID'.

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 ('Delete a Cloudcraft blueprint') and names the exact operation scope. It is immediately distinguishable from create_blueprint, update_blueprint, and get_blueprint without opening any schema.

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

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

Gives a clear precondition for invoking the tool ('after exact-id confirmation') and signals that the operation is irreversible, which frames when it is appropriate. It does not name alternatives (e.g. update_blueprint) or explicit when-not conditions, so it stops 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=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it writes a file to a specific write sandbox, it defines the default output path pattern, and it explains that overwrite=True is what replaces an existing file (clarifying the destructive hint's scope).

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 first sentence states the action and artifact up front, then Args/Returns sections are cleanly partitioned with no filler. Length is justified by the number of documented parameters, and 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 a file-export tool with 7 parameters and an output schema, the definition covers format options, path handling, overwrite semantics, and the return shape. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0% and the schema has no enums, so the description carries the full burden. It documents every one of the 7 parameters, including value domains (csv/xlsx, 11 ISO currency codes, h/d/w/m/y, effective vs stated) and defaults, adding meaning the bare string-typed schema cannot convey.

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

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

States a specific verb (Export) plus resource (a blueprint's cost estimate/budget) and the output artifact (CSV or XLSX on disk). It also differentiates itself from the closest sibling by naming export_blueprint_image and the shared sandbox, so an agent can separate the two export tools 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?

Usage is implied by the resource ('export a budget') and the sibling reference gives context about the write sandbox, but there is no explicit when-to-use or when-not-to-use guidance, nor any routing hint like 'use export_blueprint_image for diagrams instead'. Minimum viable.

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 declare destructiveHint=true and openWorldHint=true; the description explains what that destruction actually means ('overwrite... Default False — existing files are preserved') and bounds the write scope to the export directory. It also documents the return shape, so the risk profile and side effects are fully transparent rather than left to inference.

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?

Purpose is front-loaded in the first line, followed by well-organized Args/Returns sections where each entry earns its place. Minor redundancy: the CLOUDCRAFT_EXPORT_DIR variable and its default are explained across two sentences when one would suffice.

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

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

For a 6-parameter write tool with high destructive potential, the definition covers directory constraints, path resolution rules, all defaults, format-specific parameter applicability, overwrite safety, and the return payload. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: it enumerates all six parameters, gives the accepted format values (png, svg, pdf, mxgraph), states the default output path pattern, and flags that scale and transparent apply to PNG only. This is meaning the schema alone does not convey.

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

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

States a specific verb ('Render') and resource ('a Cloudcraft blueprint') with the output medium ('image file on disk'), which immediately separates it from siblings like get_blueprint, export_blueprint_budget, and create_blueprint. An agent knows exactly what this produces 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 write-restriction section gives clear operational context: writes are confined to CLOUDCRAFT_EXPORT_DIR, and the env var is named for redirecting them. It does not explicitly state when to prefer this over alternatives (e.g. vs export_blueprint_budget), but the purpose is unambiguous enough that selection is implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description usefully discloses what the payload contains (nodes, edges, groups, layout), but says nothing about size, permissions, or rate limits for what could be a large full-graph fetch.

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 core sentence is front-loaded and precise, with the payload contents in parentheses rather than a separate list. The trailing 'Args:' block partly duplicates the schema, though the UUID-source hint earns it.

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 single required parameter is documented with its source. For a one-param read tool this is nearly complete; only failure modes are 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 0%, so the description must carry the burden, and it does: it identifies blueprint_id as a Blueprint UUID and directs the agent to list_blueprints as its source. It omits any invalid-id error behavior, keeping it just short of 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 ('Fetch') and resource ('full blueprint payload') and enumerates the payload contents (nodes, edges, groups, layout), which makes it distinguishable from list_blueprints at a glance. It stops short of explicitly contrasting with the sibling list tool.

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

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

Usage is only implied: the parameter doc notes the id comes from list_blueprints, sketching a list-then-fetch flow. There is no explicit when-to-use/when-not guidance or comparison against list_blueprints or the export tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and reach profile is covered. The description only adds the domain detail that these are Cloudcraft-registered accounts used for live scans; it says nothing about pagination, result ordering, or what happens when no accounts are registered.

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. The verb and resource lead, and the qualifier adds scope 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?

For a zero-parameter read-only list tool with a full output schema, the description covers what an agent needs to select and call it correctly. Return-value details are appropriately delegated to the output schema; only cross-tool routing against list_azure_accounts/snapshot_aws 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 tool takes zero parameters, so the baseline of 4 applies. There is no parameter whose meaning the description could clarify or obscure.

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 AWS accounts') and adds useful scope ('registered with Cloudcraft for live-scan snapshots'). It is clearly distinguishable from the sibling list_azure_accounts by naming AWS, though it never explicitly contrasts with it or with snapshot_aws.

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 live-scan snapshots' implies the purpose of listing accounts (discovering targets for snapshot_aws), but there is no explicit statement of when to call this rather than another discovery or snapshot tool. Usage is inferred rather than 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=true and openWorldHint=true, so the safety and scope profile is covered. The description adds only that accounts are tied to live-scan snapshots and says nothing about result volume, pagination, or account-scope limits; with annotations covering the basics, this is an adequate-but-thin add.

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; the verb and resource lead immediately and every clause adds a scoping 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?

With no parameters, an output schema present, and annotations carrying the safety profile, the description covers what an agent needs to select and invoke this tool. Only the absence of any cross-reference to snapshot_azure keeps it short of 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?

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to disambiguate, and it correctly does not invent parameter semantics.

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 (List) and resource (Azure accounts) plus the scoping qualifier 'registered with Cloudcraft for live-scan snapshots', which clearly separates it from generic listing tools. It does not explicitly name siblings like list_aws_accounts or snapshot_azure, so a 4 rather than 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 phrase 'for live-scan snapshots' implies this is the discovery step before snapshot_azure, but the description never states when to call it versus list_aws_accounts or that its output feeds snapshot_azure. Usage is inferable 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the shape of each returned summary (id, name, tags, updatedAt), but that duplicates the existing output schema and leaves pagination or result-size behavior unstated.

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 account-wide scope is front-loaded ahead of the follow-up hint. Nothing padded or redundant in the phrasing itself.

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 no-argument, read-only list with an output schema covering return fields, the description supplies everything needed to invoke it and identifies the natural next call. Only the absence of any note on result volume or pagination keeps it short of full marks.

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 is nothing for the description to disambiguate; the 4 baseline applies. No argument syntax or filtering behavior is claimed that would need explanation.

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 every Cloudcraft blueprint (diagram)') and scopes it to 'the authenticated account'. This clearly distinguishes it from get_blueprint, create_blueprint, and the other blueprint 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 routes the agent forward: 'Use get_blueprint afterwards to pull the full node / edge JSON', which clarifies this is the lightweight enumeration step. It gives clear context but does not state when listing is unnecessary or set bounds on use.

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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the account scope and a list of returned fields, but the output schema already defines return values, leaving little behavioral context beyond structured data.

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 text. It communicates the action, resource, scope, and returned fields 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 zero-parameter read-only list tool with annotations and an output schema, the description is largely complete: it says what is listed and what fields are included. It could be slightly stronger with a note about account scoping or pagination, but those are minor given the tool's simplicity.

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 are no parameter semantics to clarify. The baseline for zero-parameter tools 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 ("List") and resource ("teams"), and scopes it to teams linked to the Cloudcraft account. It does not explicitly differentiate from siblings, but no sibling in the provided list operates on teams, so the resource itself is distinguishing.

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 guidance on when to use this tool versus alternatives, nor any stated prerequisites or exclusions. Usage is only implied by the tool name and the phrase "linked to the Cloudcraft account."

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=false, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety and idempotency profile is largely covered. The description adds that this is a live scan against AWS that yields a blueprint JSON, but omits auth requirements, whether an existing blueprint is overwritten, and rate/scope limits.

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; the scope constraint (one region) and output (blueprint JSON) arrive immediately.

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. However, for a four-parameter, live-scanning mutation the description omits the filter/exclude semantics and any precondition that the AWS account must be connected, leaving gaps an agent would hit at call time.

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 only one of four parameters (region) is even implied by the description. The optional filter and exclude parameters are never mentioned, and account_id is only obliquely implied by the AWS context, so the description does not compensate for the coverage 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 (scan), resource (one AWS region), and output artifact (blueprint JSON) plus the mechanism (Cloudcraft live-scan). The AWS scope cleanly distinguishes it from the sibling snapshot_azure.

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 guidance, no prerequisites, and no stated boundary versus list_aws_accounts or create_blueprint. The agent must infer from the tool name and the AWS/region wording that this is the region-scanning entry 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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, giving a solid safety profile. The description adds that it performs a live scan and produces blueprint JSON, but fails to explain the write side effect (e.g., whether a blueprint is created or stored) and any required permissions. With annotations present, this partial addition warrants a 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?

The single sentence is front-loaded and contains no filler. However, for a tool with four parameters and no schema descriptions, a slightly more structured explanation could be appropriate, so it is not perfectly sized.

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 four parameters (two required, 0% schema description coverage), a non-read-only annotation profile, and an output schema, the description is substantially incomplete. It omits parameter meanings, authentication requirements, and any clarification of the mutation’s effect, leaving the agent with too many gaps to call the tool confidently.

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 four parameters, so the schema offers no meaning for account_id, region, filter, or exclude. The description only indirectly hints at the region parameter ('one Azure region') and gives no information on the other three, leaving parameter usage largely 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 states a specific verb ('Scan'), resource ('one Azure region'), output ('blueprint JSON'), and method ('Cloudcraft live-scan'). It clearly distinguishes the tool from generic list/get tools, though it does not explicitly contrast with the sibling snapshot_aws or clarify whether the JSON is returned or persisted.

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 versus alternatives like snapshot_aws, list_azure_accounts, or create_blueprint. The description gives no prerequisites, exclusions, or context 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the meaningful clarification that the entire payload is overwritten (no merge semantics), but says nothing about what happens to omitted fields, permissions, or failure modes beyond what annotations provide.

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 lines of prose plus a two-entry Args block, with the mutating operation front-loaded. No filler; every element maps directly to a required parameter or the core semantics.

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 mutation with an output schema (so return values need not be described) and annotations covering safety, the description is nearly sufficient. It conveys full-replacement semantics and parameter meaning; only edge-case behavior (omitted fields, auth) is left 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%, yet the description documents both parameters: blueprint_id as a Blueprint UUID and data as the full payload with a cross-reference to create_blueprint for its shape. The cross-reference is genuinely valuable since BlueprintData's many nested fields are largely undocumented in the schema.

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

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

States a specific verb and resource — 'Replace the full data payload of an existing blueprint' — and the word 'existing' separates it from create_blueprint. It does not explicitly name sibling alternatives, but the operation and its target are 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?

'Replace the full' implies a whole-payload overwrite rather than a partial edit, and 'existing blueprint' implies the blueprint must already exist, which is useful usage context. However, it never states when to use this versus create_blueprint or delete_blueprint, nor any 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 (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description adds genuinely useful context beyond that: the returned profile is scoped to the current API key, which explains both the absence of parameters and the tool's role as a credential 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?

Two short sentences, purpose first, usage second. Nothing redundant and 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?

A read-only, zero-argument identity tool with an output schema available, so return-value detail is unnecessary in the description. Everything an agent needs to call it correctly is present.

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, which sets the baseline at 4. The description reinforces this by implying the identity is derived from the API key rather than from any argument, so an agent will not hunt for an input it should supply.

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 the Cloudcraft user profile for the current API key.' This is unambiguous and clearly distinct from every sibling (blueprints, teams, AWS/Azure accounts), none of which return identity data.

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 explicit context for when to reach for it: 'Useful as a sanity check after configuring a new key.' That is a concrete usage scenario rather than implied guidance, though it names no exclusions or alternatives (none really exist here).

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