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

Annotations already mark this as destructive and non-idempotent. The description adds valuable behavioral context by disclosing the two-phase confirmation (preview then execute with confirmed=true) and the base URL resolution order (spec, env var, or parameter), which 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?

Two sentences with no wasted words. The primary action is front-loaded, followed by the most important behavioral nuance (confirmation) and the base URL precedence. Every clause contributes meaningful information.

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

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

Given the tool's complexity (8 parameters, two-phase confirmation, no output schema), the description covers the critical flow and URL resolution. It does not describe response shapes or failure modes, but for an execution tool the confirmation mechanism is the most important context and is well described.

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 describes all 8 parameters with 100% coverage, so baseline is 3. The description additionally clarifies the semantics of two key parameters: 'confirmed' controls preview vs. execution, and 'base_url' can override other sources. This adds meaning beyond the schema without repeating it.

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

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

The description begins with 'Execute an actual HTTP request to an API endpoint,' using a specific verb and resource that clearly distinguishes this tool from sibling tools that only read or load spec data. It also mentions the two-phase confirmation, which adds to its unique identity.

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 context makes it obvious this is the tool for making real API calls versus the read-only/spec-management siblings. It does not explicitly spell out 'use this instead of swagger_get_endpoint when you want to send a request,' but the wording 'actual HTTP request' implies that distinction effectively.

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

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

Annotations already declare the tool as read-only and non-destructive. The description adds valuable context about the return value being a cached file path and instructs the user to Read that file for full details, making the tool's behavior more transparent 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?

Two short sentences, front-loaded with the primary purpose and a clear follow-up instruction. No unnecessary words.

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?

Despite lacking an output schema, the description explains the return value (brief summary and file path), what the file contains, and how to access full details, which is sufficient for a simple two-parameter read-only 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?

Both parameters are fully described in the schema with examples (path and method). The description does not add further parameter details, but since schema coverage is 100%, 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 uses a specific verb ('Get'), identifies the resource ('specific API endpoint'), and distinguishes itself from siblings by mentioning the cached JSON file path and the Read tool follow-up, making its unique function clear.

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 (get a specific endpoint's summary and path) but does not explicitly compare to alternatives or state when not to use it. It does give a follow-up instruction to use Read, implying the tool is a starting point for full details.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds valuable behavioral context beyond the annotations by disclosing the return format: a brief summary and a path to info.json. It also specifies what the file contains (title, version, servers, auth schemes, etc.), which is not available from the schema or 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, each earning its place: first states purpose, second summarizes return value, third gives an actionable follow-up instruction. It is front-loaded and contains 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 metadata tool with no parameters and no output schema, the description completely explains what to expect: a brief summary, a path to info.json, and what the file contains. The instruction to use the Read tool covers how to get full details, making the workflow clear. No gaps are apparent.

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. The description adds meaning by explaining the output, but no parameter semantics are needed. Since there is no schema coverage issue, a 4 is appropriate.

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

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

The description states exactly what the tool does: 'Get general metadata about the loaded API specification.' It uses a specific verb ('Get') and a clear resource ('general metadata about the loaded API specification'), and distinguishes itself from siblings like get_endpoint or get_schema by focusing on overall metadata rather than specific parts.

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: use this tool to get a summary and a path, then follow up with the Read tool. However, it does not explicitly say when to use this tool versus alternatives like swagger_get_schema or swagger_list_tags, nor does it mention when not to use it. The guidance is useful but only implicitly conveys the intended workflow.

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 idempotentHint=true, so the safe read nature is known. The description adds useful behavioral context: it returns a 'brief summary' and a 'path to its cached JSON file' rather than the full content directly, and indicates the file contains a 'complete deep-resolved definition' with specific elements. This aligns with annotations and adds 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?

The description is two sentences and front-loaded with the main purpose. The first sentence states the action and output; the second provides a clear next step. The enumeration of contained elements ('all properties, types, required fields, enums, defaults, nested structures') is somewhat detailed but clarifies what the cached file holds, earning 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 tool with a single required parameter and no output schema, the description sufficiently explains what the tool returns (summary + file path) and how to proceed to get the full definition. It does not mention error handling for unknown schema names, but the core usage is covered, making it complete enough for practical use.

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 the only parameter 'name' with a description and examples: 'Schema/model name (e.g. 'User', 'OrderResponse')'. The tool description reinforces that it targets a 'specific schema/model' but adds no new semantic details beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get a brief summary of a specific schema/model and the path to its cached JSON file containing the complete deep-resolved definition.' It uses a specific verb ('Get'), a specific resource ('schema/model'), and distinguishes itself from siblings like swagger_list_schemas (which lists all schemas) by focusing on a single named schema and returning a file path.

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 explicit follow-up guidance: 'Use the Read tool on the returned file path to see the full schema.' This tells the agent what to do after calling the tool. However, it does not explicitly mention alternatives or when not to use the tool, so it stops short of the highest rating.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds behavioral context about return fields, pagination for large APIs, and the presence of a cacheFile path for each entry, which is useful for post-processing.

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 four short sentences, each serving a purpose: listing, filtering, pagination, and return detail. It is front-loaded with the primary action and contains 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?

Given the read-only annotations and optional parameters, the description covers what the tool returns, how to filter, and how to paginate. The absence of an output schema is mitigated by the explicit mention of returned fields and cacheFile. It is adequate 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?

Schema coverage is 100%, so baseline is 3. The description adds value by grouping parameters into filters (tag, method, keyword) and pagination (limit, offset), and by explaining that cacheFile paths are included in results, which is not in the schema. This clarifies how parameters work together.

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 it lists all API endpoints with specific fields (method, path, summary, tags), which distinguishes it from sibling tools like swagger_get_endpoint (single endpoint) and swagger_list_tags (tags only). It also mentions filtering and pagination, giving a complete sense of 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 explains the tool is for listing endpoints with filtering options and pagination, and mentions that each entry includes a cacheFile path for detailed info, implying the next step. However, it doesn't explicitly name alternatives like swagger_get_endpoint for single-endpoint details, so it lacks a direct when-not-to-use statement.

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

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

Annotations already declare read-only and non-destructive behavior, so the safety profile is covered. The description adds valuable context about returned fields (name, type, description, property count) and supports filtering/pagination, going beyond the annotation-only information.

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 concise sentences, front-loaded with the main action ('List all model/schema definitions') followed by the output summary and feature hints. No fluff or redundant information.

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

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

For a simple listing tool, the description is complete. It states what the tool returns (fields), mentions filtering and pagination, and the annotations confirm safety. No output schema exists, but the described output is sufficient for the intended use.

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?

All three parameters (limit, offset, keyword) are fully described in the schema, achieving 100% coverage. The description only restates that filtering and pagination are supported, which adds no new meaning beyond the existing schema descriptions.

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 lists all model/schema definitions in the API spec, with a specific verb ('List') and scope ('all model/schema definitions'). It also lists the expected output fields (name, type, description, property count), distinguishing it from sibling tools like `swagger_get_schema` which likely targets a single 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 description implies use cases: enumerating schemas, filtering by keyword, and paginating. However, it does not explicitly mention when not to use it or provide direct alternatives (e.g., 'use get_schema for a specific schema'). The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavioral detail by stating it 'shows how many endpoints belong to each tag,' which goes beyond the schema and gives insight into return content. No contradiction with annotations exists.

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

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

The description is two sentences, front-loaded with the core action ('List all tags defined in the API spec'), and every sentence adds value: the second explains the grouping purpose, and the third clarifies the output includes counts. 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 simple list tool with no parameters and no output schema, the description sufficiently explains what the tool does and what information it returns (tags and counts). It does not detail the exact response structure, but given the tool's simplicity, the description is complete enough for an agent to select and 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?

The tool has zero parameters, and the input schema is empty with 100% coverage. The description does not need to explain parameter semantics, and the baseline for 0-parameter tools is 4. It adds no param-specific info but is not required to.

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 primary function: 'List all tags defined in the API spec.' It specifies the resource (tags) and the verb (list), and adds context that tags group related endpoints. This distinguishes it from sibling tools like list_paths and list_schemas, which operate on different resources.

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 implicitly conveys when to use the tool (when you need to see tags and their endpoint counts), but it does not explicitly mention alternatives or provide exclusionary guidance. It lacks a direct 'use this instead of...' statement, making usage guidance only implied rather than explicit.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds valuable context beyond annotations: it caches to local JSON files, is used by all subsequent tools, and must be called first. It doesn't disclose all details (e.g., overwrite behavior, error handling), but the added context satisfies the need for behavioral transparency beyond the structured hints.

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, each earning its place: purpose and formats, caching behavior, and required ordering. It is front-loaded and free of redundant or vague 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 moderately complex setup tool, the description covers purpose, accepted formats, caching, subsequent tool dependencies, and invocation order. Given the high schema coverage and suitable annotations, the description is complete enough for an agent to select and use this tool correctly. It even notes an environment-variable shortcut, which is valuable operational context.

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%: both 'url' and 'headers' already have clear descriptions. The tool description mentions JSON/YAML support, but that is already embedded in the url parameter description. No additional parameter-level meaning is provided beyond what the schema already gives, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Load and parse'), names the resource ('Swagger 2.0 or OpenAPI 3.x specification from a URL'), and distinguishes this tool from siblings by framing it as the initialization step for all subsequent tools. It also specifies supported formats (JSON/YAML), making the 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 explicit usage guidance: 'Must be called first before using other tools' and notes the exception when SWAGGER_URL env var is set. This clearly tells the agent when to invoke this tool versus alternatives (the sibling tools that operate on the loaded spec).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds meaningful behavioral detail: it specifies which parts of the spec are searched and that results include cache file paths for later lookup. This goes beyond the annotations without contradicting them.

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, front-loaded with the action and resource, and every sentence adds value (what is searched, where, and what is returned). 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?

The description sufficiently explains the tool's purpose, search scope, and output type for a simple search tool. It lacks an explicit output schema, but the return description ('matching items with cache file paths') is adequate. Slight gap: it does not explain how 'scope' modifies results, though the schema covers that.

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% coverage with descriptions for both 'keyword' and 'scope'. The description adds no new parameter-specific semantics beyond what the schema provides, so the baseline score 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 clearly states the tool searches the API specification by keyword, enumerating the searched fields (paths, summaries, descriptions, operation IDs, schema names) and the return type (cache file paths). This distinguishes it from sibling list tools like list_paths and list_schemas, making the 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 implies usage for keyword-based lookup across the spec, which differentiates it from listing or retrieval tools. However, it does not explicitly state when not to use it or mention alternatives, so it lacks the explicit exclusion/alternative guidance 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 (which indicate non-read-only, idempotent, non-destructive), the description adds key behavioral detail: the token is used as-is with no automatic Bearer prefix, and clear=true removes the current token. This informs the agent of subtle security/format implications that annotations do not capture.

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 action and followed by essential usage details. Every sentence contributes to understanding the tool without repetition 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 simple two-parameter tool with no output schema, the description adequately covers the operation: setting/clearing auth for swagger_call_api, including the token format nuance. It could mention persistence across calls or how to view the current token, but such details are not necessary for basic correct 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 has 100% parameter coverage, with detailed descriptions for both clear and token. The description reinforces the 'no automatic prefix' rule but adds minimal new parameter meaning beyond what the schema already provides. The reference to swagger_call_api is contextual rather than parameter-specific.

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: dynamically setting or clearing the Authorization header for swagger_call_api. The verb-resource pairing is specific (set/clear + Authorization header), and it distinguishes itself from the sibling tools by being uniquely focused on auth management.

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 indicates the tool is used for swagger_call_api, giving clear usage context. It explains how to set a token and how to clear it via clear=true. However, it doesn't explicitly contrast with alternatives or state when not to use it; given that it's the sole auth tool among siblings, the context is 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?

Annotations already declare idempotency and non-destructiveness, and the description adds the concrete behavior of rebuilding the local file cache, which is useful. It does not detail error handling or side effects of providing a new URL, but the existing annotation coverage lowers the bar.

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 crisp sentences accomplish the description's goal without redundancy. The first sentence states the action, the second gives the usage trigger and param note.

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

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

For a tool with two optional parameters and no output schema, the description covers the core functionality and usage scenario adequately. It does not explicitly differentiate from swagger_load_spec, but the purpose and annotations provide enough context for an agent to decide to use it when a spec refresh is needed.

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 describes both parameters with full coverage; the description's 'Optionally provide a new URL' merely restates the schema's optionality, adding no new semantic information. Baseline for 100% schema coverage is 3, and the description does not elevate it.

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

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

The description uses specific action verbs 'Re-fetch' and 'rebuild' to state its function, clearly distinguishing it from read-only sibling tools by indicating it modifies the local cache. The mention of Swagger/OpenAPI spec identifies the resource.

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 states when to use ('when the upstream spec has changed'), providing clear context for invocation. Does not name alternatives or exclusions, but the 'when' clause is sufficient for a simple cache refresh tool.

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