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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: it returns 1–3 clarifying questions plus a diagram type, is intended to be called before generation, and is free. No contradiction with annotations; the description supplements them with output and sequencing details.

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 concise sentence with the key output details front-loaded. The added 'Free' is a useful behavioral note, and there is no wasted 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 simple one-parameter read-only tool with no output schema, the description adequately explains the return content (1–3 questions plus a diagram type), the count, and the intended timing. It is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema has one required parameter with 100% description coverage, so the baseline is 3. The description only adds that the prompt is expected to be vague, which is marginal additional meaning beyond the schema's 'Your prompt'.

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 ('Get') and clearly identifies the resource: 1–3 clarifying questions and a suggested diagram type for a vague prompt. It also states the timing ('before generating'), which distinguishes it from generation-focused sibling 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 description clearly indicates when to use the tool: for a vague prompt, before generating. It does not explicitly name alternatives or exclusions, but the 'before generating' context provides situational guidance relative to sibling tools like generate_diagram.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description explains the concrete consequences: soft-delete, removal from list_diagrams, and inability to fetch. It also emphasizes user confirmation, adding significant behavioral context that annotations alone do not 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 sentences, front-loaded with the action, and no redundant wording. The 'soft-delete' clarification and the destructive warning each add value without bloat.

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 delete operation with no output schema, the description covers the action, ownership prerequisite, behavioral effects, and safety warning. It does not specify return values, but the consequence is clearly stated, making it complete for typical usage.

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 covers 100% of the single parameter (diagram_id) with a clear description ('The diagram id'). The tool description adds no additional parameter semantics, so the baseline 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 clearly states the action ('Delete'), resource ('diagram'), and adds the specific 'soft-delete' behavior and ownership constraint ('a diagram you own'). It does not explicitly differentiate from sibling tools like update_diagram or revert_diagram, which prevents 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 description says 'Confirm with the user before calling — this is destructive' and implies use only for owned diagrams, but it does not explicitly mention when NOT to use this tool or provide alternatives among the many siblings. Usage guidance is present but only implicit.

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?

Beyond the annotations, the description adds key behavioral details: it creates a new version, returns updated XML, and costs credits. These are not inferable from readOnlyHint=false or destructiveHint=false alone. The description also clarifies that the tool mutates the diagram, which is consistent with the annotations (no contradiction).

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

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

The description is concise and information-dense: a single opening sentence states the action and example, followed by two short sentences conveying versioning, XML return, credits, and user confirmation. Every sentence earns its place with no 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 only 2 parameters and no output schema, the description covers the main expectations: it returns updated XML, creates a new version, and costs credits. It does not discuss failure modes or prerequisites, but for a straightforward edit tool the description is largely complete. The lack of differentiation from update_diagram is a minor gap.

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

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

The input schema already provides 100% coverage for both parameters, including clear descriptions. The example 'add a Redis cache' in the tool description gives a hint about edit_prompt format, but does not add substantial meaning beyond the schema. Baseline 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 clearly states the tool's function: 'Apply a natural-language change to an existing diagram' with a concrete example. This makes the purpose specific and unambiguous. However, it does not explicitly differentiate from the sibling tool 'update_diagram', which likely serves a similar editing purpose.

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 usage context: natural-language edits, costs credits, and confirms with the user before calling. It also warns that it mutates the diagram. It does not explicitly mention alternatives or exclusions, but the 'confirm with user' instruction is an important guideline.

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 readOnlyHint=true, which the description does not contradict. However, the description adds no behavioral context beyond the purpose and the claim 'Free'; it does not disclose limitations, rate limits, or how the input is handled. With annotations covering safety, the description contributes minimal additional transparency.

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, concise sentence with no redundant phrasing. The word 'Free' is somewhat unnecessary but does not detract. It is front-loaded with the core function, making it efficient and easy to parse.

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

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

The tool is simple with good schema coverage and a read-only annotation, but no output schema exists. The description does not explicitly state what the response contains, nor does it differentiate from the sibling 'clarify_prompt'. The implied return of an enhanced prompt is understandable but lacks detail.

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%, with clear descriptions for both 'prompt' and 'cloud_provider', including allowed values. The description does not elaborate on parameter usage, but the schema already provides sufficient meaning, so a 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 ('Turn') and clearly identifies the resource ('rough idea' into 'detailed generation prompt'). It effectively conveys the tool's function, though it does not explicitly distinguish from the sibling tool 'clarify_prompt'.

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 provides no guidance on when to use this tool versus alternatives like 'clarify_prompt'. It does not state prerequisites, exclusions, or recommended contexts beyond the implied purpose of enhancing a rough prompt.

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 the description adds valuable behavioral details: it returns file content directly and warns that free-plan SVG exports carry a watermark. This goes beyond the schema and annotations, though it does not mention potential rate limits or authentication requirements, which are less critical for a read-only export tool.

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 three concise sentences, front-loaded with the core purpose ('Export a diagram as a raw file'). Every sentence adds useful information: formats, return behavior, pricing, and watermark caveat. There is no fluff or redundancy, making it highly efficient for an agent to parse.

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 tool with two well-documented parameters and no output schema, the description covers all essential aspects: what formats are supported, what the response contains, cost implications, and a critical watermark limitation. It is complete enough for an agent to select and invoke this tool without confusion.

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 input schema already has 100% description coverage for both parameters, so the baseline is 3. The description enriches the `format` parameter by noting that `drawio` files are openable at app.diagrams.net and that SVG exports may have a watermark, adding value beyond the enum. The `diagram_id` parameter is not further elaborated, but the schema already describes it adequately.

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 clearly states the verb 'export' with the resource 'a diagram' and specifies the output formats `drawio` and `svg`, distinguishing it from sibling tools like `get_diagram` or `generate_diagram`. It also clarifies the output type ('raw file') and return behavior, making the tool's purpose unambiguous.

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

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

The description provides clear context: use this tool when you need a raw file export in drawio or svg format. It also notes that exports are free and free-plan SVG exports carry a watermark, which informs usage decisions. However, it does not explicitly state when not to use it or name alternatives such as `get_diagram` for structured content, so it falls 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the tool 'Creates a new version' and 'Costs credits', which are significant behavioral side effects critical for an agent to know before invoking it. This adds substantial value.

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 short, focused sentences: the main action, the side effect on versions, and the cost. No unnecessary words, and the key information is front-loaded.

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 covers the essential aspects: targeted scope, version creation, and cost, which are sufficient for a mutation tool. It could mention the return value or failure modes, but given the tool's simplicity and annotations, it is largely 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 schema already describes all four parameters with 100% coverage, including the mapping to get_warnings fields. The description does not add additional parameter meaning, so it stays at the baseline of 3.

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 the specific verb 'Resolve' targeting a 'Well-Architected warning' and adds the constraint 'single' and 'leaving the rest of the diagram untouched', which clearly distinguishes it from broader diagram-editing tools like edit_diagram or update_diagram.

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 provides clear context for use: fixing a single warning from get_warnings, implying it is the targeted alternative to broader diagram edits. However, it does not explicitly name alternatives or state when not to use it, so it falls 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 indicate the tool is mutating (readOnlyHint false) but not destructive (destructiveHint false). The description adds meaningful context beyond annotations: it specifies the operation creates a private copy, returns the new diagram id, and the source type (public gallery/curated template). This clarifies the non-destructive mutation behavior without contradicting 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?

The description is two sentences, perfectly front-loaded with the action ('Copy a PUBLIC gallery diagram or curated library template'), followed by destination, purpose, and return value. Every clause adds value with no redundancy or fluff.

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 tool with no output schema, the description covers the essential operation, source, destination, and return value. It does not mention edge cases like invalid IDs or permissions, but these are not critical for basic usage. The presence of annotations and a clear schema make this sufficiently complete, though a 5 would require more detail on failure modes or usage prerequisites.

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 for the single parameter is 100% (diagram_id is described as 'A public/library diagram id from search_gallery'), so baseline is 3. The description does not add much beyond the schema—it merely reiterates the source type. No additional semantic richness is provided, so a 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 clearly states a specific verb 'Copy' and resource 'public gallery diagram or curated library template', with the destination ('into your own account (private)') and purpose ('so you can edit it'). This distinguishes it from sibling tools like generate_diagram (create new), edit_diagram (modify existing), and import_diagram (likely external import), making the purpose unmistakable.

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 provides clear context: it's for copying a public/library diagram into a private account for editing. It implies usage after search_gallery (as stated in the schema) but does not explicitly name alternatives or state when not to use it. The context is strong enough to guide selection, but lacks explicit exclusions compared to 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 clarify readOnlyHint=false and destructiveHint=false. The description adds valuable non-obvious context: 'Costs credits' and the exact return payload (id, XML, warnings, score, credits used). It does not elaborate on persistence or side effects beyond generation, but this is sufficient given annotations cover the mutation/destruction profile.

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 two sentences, immediately front-loaded with the core action, and every phrase earns its place: what it creates, the input type, the returned data, and the cost. 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?

Given the tool has 4 parameters (1 required) and no output schema, the description does a good job explaining the return format and cost. It does not explicitly state whether the diagram is saved/persisted (relevant for later retrieval via get/list tools), which is a minor gap. Overall, it conveys enough for an agent to invoke the tool and interpret the response.

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 all four parameters have meaningful descriptions within the schema itself. The tool description adds no additional parameter-level information beyond what the schema provides; it only frames the prompt as natural-language, which is already present. 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 clearly states a specific action ('Create a new cloud architecture diagram from a natural-language prompt') and identifies the resource and method. It distinguishes itself from sibling tools like edit_diagram, update_diagram, and delete_diagram by emphasizing creation from a prompt, and it lists concrete outputs (diagram id, XML, warnings, score, credits used).

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 'Create a new' provides clear context that this tool is for initial generation, not modification or deletion. However, it does not explicitly name alternatives (e.g., 'use edit_diagram to modify'), so it lacks explicit exclusions. This fits a 'clear context, no exclusions' level.

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 readOnlyHint annotation already signals a safe read operation. The description adds the specific return fields but doesn't disclose additional behaviors like error handling or not-found cases. Given annotation coverage, a score of 3 is appropriate.

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, information-dense sentence that front-loads the action and resource. Every word contributes to understanding the tool's purpose and return value.

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 fetch operation, the description covers the essentials: what is fetched and what is returned. No output schema exists, so explaining return values is necessary and done well. It could mention error behavior but that's not critical for this basic get tool.

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

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

Schema coverage is 100% and the schema already describes diagram_id as 'The diagram id'. The description's 'by id' adds no further semantic detail, so the baseline of 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 clearly states the action ('Fetch'), the resource ('a diagram by id'), and the specific return contents ('title, draw.io XML, and Well-Architected score'). This distinguishes it from sibling tools like get_warnings or get_version, which target different 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?

The description clearly implies using this tool to retrieve a diagram's full content by its ID. It doesn't explicitly exclude alternatives or mention when not to use it, but the straightforward purpose and sibling differentiation provide clear context.

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?

Beyond the readOnlyHint annotation, the description discloses the possible statuses (pending/done/failed), the conditions for including re-laid XML and warnings/score, and that it is free. This adds meaningful behavioral context though it doesn't mention error handling or polling intervals.

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 two sentences, front-loaded with the core purpose, and every phrase adds value. It efficiently covers what the tool does, outcomes, and a billing note 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 simple polling tool with read-only annotations and no output schema, the description sufficiently covers the typical statuses and data returned when complete. It does not mention potential errors or caveats, but the scope is small and the essentials are 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 input schema already documents both parameters (job_id and diagram_id) with clear descriptions, and schema coverage is 100%. The tool description adds little beyond referencing job_id as returned by relayout_diagram, so the schema carries the 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?

The description clearly states the tool's purpose: checking the status of an async re-layout job started by relayout_diagram. It specifies the resource (re-layout job) and the action (check status), distinguishing it from sibling tools like get_diagram or relayout_diagram.

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 implies clear usage: use this tool after starting a re-layout with relayout_diagram, passing the returned job_id. It does not explicitly list when not to use it, but the context is unmistakable and adequate 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?

The annotation readOnlyHint already communicates that this is a safe read operation. The description adds 'Free' and specifies the output areas (plan, credits, cost estimates), but it does not disclose deeper behavior such as response format or rate limits. This is acceptable for a simple read-only tool, but it does not go beyond annotations significantly.

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 sentence that front-loads the action and delivers all necessary information with no wasted words. 'Free' is an extra useful trait that justifies 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 zero-parameter, read-only tool without an output schema, the description covers the core information: what the tool returns (plan, credits, per-action cost estimates). It does not explain the return format, but that is less critical here. A minor gap is the lack of differentiation from get_usage_history, but the tool's simplicity keeps it complete enough.

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, and the schema covers 100% of the parameter space (an empty object). The description adds no parameter-level detail, but none is needed. The baseline for zero parameters 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 uses a specific verb ('Show') and clearly identifies the resource: current plan, credits remaining, and per-action cost estimates. It also implicitly distinguishes itself from the sibling get_usage_history by focusing on current usage rather than historical 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?

The description provides clear context for when to use this tool (checking current usage and credits), but it does not explicitly mention alternatives or exclusions. Since the sibling get_usage_history exists, a brief 'for history, see get_usage_history' would have earned a 5, but the current wording is still clear enough.

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?

Beyond the readOnlyHint annotation, the description adds behavioral details: newest-first ordering, inclusion of diagram and surface, and the session-scoped running tally. It also states 'Free (read-only)', reinforcing safety without contradicting 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?

The description is three sentences with no filler. It front-loads the primary function, provides a direct use case, and adds a key additional detail about the session tally, all in a compact structure.

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 covers the main purpose, returned fields (credit, diagram, surface, session tally), and ordering. With no output schema, it compensates well, though it could mention pagination or the specific return shape. The schema covers parameters, so the description is sufficiently complete for 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% with descriptions for all 7 parameters. The description adds context for action, source, and diagram_id by mentioning task types and surfaces, but doesn't explain limit, since, until, or cursor beyond the schema. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's function: 'List how much credit each past task charged' with ordering, diagram, and surface details. It distinguishes itself from siblings like get_usage by emphasizing per-task history, not total usage.

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 a concrete use case: 'Use this to answer "how much did each task cost?"' and mentions the session tally. However, it doesn't explicitly mention when not to use it or direct users to alternative tools such as get_usage for overall consumption.

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 readOnlyHint annotation already covers safety, and the description adds that it returns XML + score and is 'Free', which are useful behavioral traits. It does not describe the exact return format or error behavior, but the additions go 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?

The description is a single front-loaded sentence with an optional parenthetical example and a separate one-word sentence 'Free.' Every word adds value and there is no 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?

For a simple read-only tool with two parameters and no output schema, the description fully covers what the tool returns, why to use it, and the cost (Free). The sibling context and schema round out the needed information.

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% for both parameters, so the baseline is 3. The description does not add extra parameter-level detail beyond the schema, but the schema itself already describes each parameter adequately.

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 clearly states the tool fetches a specific version's XML and Well-Architected score, using the verb 'fetch' with a specific resource. It distinguishes from siblings like list_versions and revert_diagram by specifying the exact output and use case.

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 'e.g. to inspect before reverting' provides a concrete usage scenario, implicitly guiding the agent to use this tool for pre-revert inspection. It doesn't explicitly exclude alternatives, but the example is clear enough for simple read-only context.

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 readOnlyHint annotation already declares this as a safe read operation, lowering the burden. The description adds useful context by noting the return structure (type, component, message) and the word 'Free,' which may indicate no cost or no restriction. It does not contradict the annotation and provides a bit more behavioral context beyond the structured fields.

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 one concise sentence that gets straight to the point. The extra 'Free' is a minor addition but does not detract. There is no unnecessary verbosity, and the key information is front-loaded.

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 tool with one parameter, no output schema, and a read-only annotation, the description fully covers the essential aspects: what it lists and what each item contains. It does not need to explain return values in more detail since the fields are listed. The description is sufficient for an agent to know what to expect.

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 fully documents the only parameter (diagram_id) with a description ('The diagram id'), achieving 100% coverage. The description does not add any parameter-specific meaning beyond the schema, which is the baseline for full schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('List') and resource ('Well-Architected findings for a diagram'), and it specifies what each finding contains (type, component, message). This makes it distinct from siblings like fix_warning, which modifies warnings, and get_diagram, which retrieves the diagram itself.

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 implies usage: to retrieve warnings for a diagram. However, it does not explicitly mention when to use this tool versus alternatives, such as fix_warning for addressing warnings, nor does it state any prerequisites or exclusions. This is acceptable but lacks explicit guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows it's a write that is not destructive. The description adds 'Validated and sanitized' which is useful behavioral context about input processing, and 'Free (no AI)' clarifies cost/processing traits. No contradictions with 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?

Two sentences, front-loaded with the main purpose, and each sentence provides distinct value: the first explains what the tool does, the second adds validation and cost details. 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?

For a moderately simple import tool with 4 parameters fully described in schema and no output schema, the description covers the core behavior and safety profile. It does not mention error handling or file size limits, but these are not essential for an agent to correctly invoke the tool given the schema. The context signals and siblings help further, and the description adequately positions this tool relative to them.

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 documents all four parameters with clear descriptions (xml, title, diagram_type, cloud_provider). The description's mention of 'draw.io mxGraphModel/mxfile XML' reinforces the xml parameter but adds no new meaning beyond the schema. Baseline of 3 is appropriate given high schema coverage.

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

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

The description states a specific verb ('Import'), a specific resource ('draw.io (mxGraphModel/mxfile) XML document'), and the outcome ('as a new diagram in your account'). This clearly distinguishes it from siblings like generate_diagram or edit_diagram, which focus on creation or modification rather than importing existing XML.

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 implies when to use this tool: when a user has an existing draw.io XML document to bring into the account. It also notes 'Free (no AI)' which hints at a non-AI alternative to generate_diagram. However, it does not explicitly name alternatives or list when-not-to-use conditions, so there is room for a more explicit exclusion.

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 the description adds 'Free' and the specific informational content returned. While it doesn't disclose rate limits or other edge behaviors, the combination of annotations and description covers the safety profile adequately for a simple discovery endpoint.

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

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

A single, front-loaded sentence that states purpose, content, and usage context without any unnecessary words. Every part 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?

Given the tool's simple read-only nature, zero parameters, and no output schema, the description fully covers what an agent needs: what the tool returns and why to call it. Nothing important 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 has zero parameters, so the schema fully covers parameter semantics. The description adds no parameter detail, but none is needed. Baseline for 0 params is 4, which 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 'Discover' and clearly defines the resource: 'valid diagram types, cloud providers, and export formats'. It also distinguishes itself from siblings by explicitly naming generate_diagram and export_diagram as tools that depend on this capability.

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 explicitly states when to use the tool: 'so you pass valid values to generate_diagram / export_diagram'. This gives clear context for invocation. It doesn't mention when not to use it, but the tool's unique purpose makes alternatives unlikely.

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?

With readOnlyHint=true in annotations, the description adds value by disclosing pagination behavior (newest first, cursor-paginated) and the return shape (id, title, cloud, type). It does not contradict the annotation and provides useful behavioral context beyond what the annotation already conveys.

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, well-structured sentence that front-loads the action and includes essential details (ordering, pagination, returned fields) without any filler. Every word 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 simple listing tool with two optional parameters and no output schema, the description is complete: it explains the scope ('your diagrams'), ordering, pagination, and return fields. The readOnlyHint annotation covers safety, and the schema covers parameter details, so nothing important 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 input schema already provides full coverage (100%) with clear descriptions for both parameters (limit as page size with default, cursor as next_cursor from previous call). The description only mentions 'cursor-paginated', which adds no new semantics beyond what the schema already states.

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 clearly states the tool's purpose with a specific verb ('List') and resource ('your diagrams'), and distinguishes it from sibling tools like get_diagram by indicating it returns multiple diagrams. It also specifies ordering and returned fields, leaving no ambiguity about the tool's function.

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 implies usage by saying 'List your diagrams', but does not explicitly state when to use this tool versus alternatives such as get_diagram or list_versions. There is no mention of exclusions or specific contexts where a different tool would be more appropriate.

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 readOnlyHint annotation already declares this as a safe read operation. The description adds value by disclosing the ascending order and the `is_current` field, but does not discuss pagination behavior (like defaults or cursor usage) which could be relevant for large histories. This is sufficient for a read-only list tool with schema coverage.

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 two sentences long, immediately states the core purpose, and includes only essential extra information (order, is_current, related tools). Every word contributes meaning, with no fluff or repetition.

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

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

For a simple read-only list tool with a fully documented schema and a readOnlyHint annotation, the description adequately covers the return characteristics (ascending, is_current) and intended companion tools. It would be incomplete if output schema were absent, but the description still conveys the key return field (`is_current`) and ordering, which is sufficient for this complexity.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters (diagram_id, limit, cursor). The description does not add additional parameter-level semantics beyond the schema, such as examples or edge cases, so baseline 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 a diagram's version history'. It also distinguishes itself from siblings by noting the ascending order and `is_current` marker, which makes it clear this is about the full history rather than a single version (get_version) or mutation (revert_diagram).

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 'Use with revert_diagram / get_version' provides clear context on how this tool fits into a workflow, implying it is for inspecting history before reverting or fetching a specific version. It does not explicitly state when NOT to use it or name alternatives for other scenarios, but the pairing gives strong usage 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?

The description goes far beyond the readOnlyHint/destructiveHint annotations by disclosing the async nature, token-based credit cost, confirm=true requirement, return payload (XML + warnings/score), and fallback to a job_id for polling. This substantially enriches the agent's understanding of the tool's behavior.

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 three sentences with no fluff, starting with the core purpose, then covering async behavior, cost, confirmation, and polling. 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?

Given the tool's complexity (async job, credit cost, polling), the description fully covers the operational flow, return contract, and points to the relevant sibling tool for status. With no output schema, the description appropriately explains what the agent should expect.

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% with both parameters already described (diagram_id and confirm). The description reiterates the confirm requirement but adds no new parameter-level details beyond what the schema's property descriptions already provide, so the schema carries the semantic 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 explicitly states the tool re-arranges a diagram's layout for readability, using a specific verb and resource. It distinguishes itself from editing or updating content by focusing on layout and mentions the async job behavior and return values.

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 provides clear context for use: improving layout, async execution, credit cost, and confirmation requirement. It also refers to get_relayout_status for polling when jobs are still running, but it does not explicitly state when not to use this tool versus other diagram 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=false and destructiveHint=false; description adds the 'Free (no AI)' cost note and clarifies the version source, but does not describe post-revert behavior like whether a new version is created or if the current version is overwritten. No contradiction with 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 short sentences that are front-loaded with the action; includes only essential usage and cost information with no redundant elaboration.

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 mutation tool with two optional parameters and an explicit either/or rule, the description provides enough context to select and invoke it correctly; however, it does not mention expected return value or post-revert state, but no output schema is present so this is not strictly required.

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 covers all parameters with descriptions (100% coverage); description adds the exclusive 'either version_id or version_number' constraint which is not encoded in schema, clarifying that exactly one of these should be provided.

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

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

Uses specific verb 'revert' with resource 'diagram' and references list_versions as source; clearly distinguishes from sibling tools like get_version and list_versions by its mutating action.

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?

States 'from list_versions' guiding the prerequisite step and 'Pass either version_id or version_number' specifying parameter usage; doesn't explicitly mention when not to use it or name alternatives, but the context implies it is for undo/restore operations.

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 readOnlyHint annotation already covers safety, so the description's main contribution is specifying the scope (public community and library templates) and the result shape (id, title, source). This adds useful behavioral context beyond the annotation without contradicting it. No rate limits or auth details, but for a read-only search tool, that is acceptable.

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 two sentences long, front-loaded with the verb and resource, and every word earns its place. It covers purpose, return values, and a follow-up action with zero filler.

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

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

Given the six optional parameters and no output schema, the description provides a clear summary of the return value (id, title, source), which is helpful. It could improve by hinting at pagination or filter options, but the schema covers those details. The mention of fork_template adds context for how the result should be used. Slightly incomplete but sufficient.

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 explains all six parameters. The description adds a small amount of semantic value by indicating that results are categorized by 'community/library', which aligns with the 'source' parameter, and by mentioning the returned fields. It does not elaborate on filters or pagination, but that is already in the schema. Baseline 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 clearly specifies the action ('Search') and the resource ('public community diagrams and curated library templates'), and distinguishes it from sibling tools by stating its purpose: finding reusable starting points. It also mentions the key returned fields (id, title, source) and connects to fork_template, leaving no ambiguity about what the tool does.

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 'to reuse as a starting point' gives clear context for when to use this tool. The mention of 'Fork one with fork_template' explicitly directs the user to a follow-up tool, implying this is the search step before forking. However, it does not explicitly state when not to use this tool or name alternatives for community vs library sources, so it falls slightly 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?

The description adds behavioral context beyond annotations by noting private visibility requires a paid plan and the tool is free (no AI). Annotations only indicate readOnly=false and destructive=false, so the description enriches understanding of prerequisites and side effects.

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 three short sentences, each providing distinct value: capabilities, usage instruction, and cost/restriction. It is front-loaded with the main purpose and contains no redundant text.

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

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

The description covers key aspects: update types, partial update semantics, paid restriction for private, and no-AI caveat. It does not mention return values, but with no output schema, this is acceptable. Sufficiently complete for a simple update 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 description maps semantic actions (rename, change visibility, replace XML) to specific parameters and clarifies partial updates. Although schema descriptions cover all parameters, the description reinforces optionality and usage intent.

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 clearly states the tool updates a diagram's metadata or XML, enumerating rename, visibility change, and XML replacement. It uses a specific verb 'update' with resource 'diagram', but does not explicitly distinguish from sibling tools like edit_diagram.

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 context on supported actions and instructs to 'Pass only the fields you want to change,' implying partial updates. It does not explicitly mention when to use this tool instead of alternatives, but does not mislead.

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?

Beyond the readOnlyHint annotation, the description discloses the specific data returned (account, plan, scopes, live/test mode) and adds a cost-related trait ('Free'). This provides meaningful context about behavior and output, exceeding minimal annotation coverage.

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 one concise sentence plus 'Free.'—no fluff. The core action and output are front-loaded, making it highly scannable and efficient.

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 the tool's simplicity (no params, no output schema, readOnly annotation), the description fully explains what the tool does and what it returns. It lists all key output fields and the cost aspect, making it complete for an agent to invoke 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?

The tool has zero parameters, so the baseline is 4. There is no parameter information to add, and the description appropriately focuses on the tool's output rather than any input 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?

The description clearly states the tool's function: 'Show the account, plan, scopes, and live/test mode of the configured API key.' It uses a specific verb ('Show') and resource, and it distinguishes itself from sibling tools, none of which focus on identity/configuration.

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 implies usage as a diagnostic tool for checking API key configuration, and the 'Free' note hints at no cost. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions. For a simple zero-parameter tool, the context is clear but not explicitly guided.

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