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 safety profile is known. The description adds useful behavioral context about error handling: it returns errors if the spec is not loaded or if the path/method is not found, with suggestions. This goes beyond the annotations and helps the agent anticipate failure modes.

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 well-organized into clear sections: purpose, usage context, Args, Returns, Examples, and Error Handling. It is front-loaded with the main purpose, and every section provides necessary information without unnecessary flourish. The length is justified by the richness of detail, making it easy to scan.

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 3 required parameters, no output schema, and moderate complexity, the description covers all necessary context: what the tool returns, when to use it, examples of concrete usage, and error handling. It also notes the prerequisite that a spec must be loaded, which is essential for the tool to function. Overall, it gives the agent a complete picture.

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 every parameter has a description in the schema, so the baseline is 3. The description adds value by repeating parameter definitions in an Args section and, more importantly, by providing examples that show how to map natural language requests to spec_name, path, and method. These examples clarify parameter usage beyond the schema.

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

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

The description clearly states the tool 'gets detailed information about a specific API endpoint' including parameters, request body, responses, and security. It distinguishes from swagger_list_paths by mentioning it is used after listing paths, but does not differentiate from the closely named sibling swagger_get_endpoint_full, which could confuse an agent selecting between the two.

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 says to use this tool after swagger_list_paths to drill down into a specific endpoint's complete details. It provides concrete examples of user intents and parameter mapping. However, it does not mention any alternatives or when NOT to use this tool (e.g., when swagger_get_endpoint_full would be more appropriate), so it 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?

The description discloses behavioral details beyond annotations: it resolves all $refs recursively, detects and marks circular references, and returns errors for missing specs or invalid paths/methods with suggestions. Annotations already declare read-only/idempotent safety, and the description adds functional 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 well-structured with a clear opening statement, followed by contrast, usage guidance, args recap, return description, and error handling. Despite being lengthy, every section adds information—no fluff. It is front-loaded with the core purpose.

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 read-only query tool without an output schema, the description adequately covers expected return, error scenarios, and circular reference behavior. It also provides examples and usage context, making it self-contained for an agent.

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 with descriptions for all three parameters; the description restates them but adds value through examples that map natural language requests to concrete parameter values. The schema itself includes enums and example paths, so the incremental contribution is moderate but useful.

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 provides detailed endpoint information with all $ref resolved recursively, using a specific verb ('Get') and resource ('endpoint details'). It explicitly distinguishes itself from swagger_get_endpoint by highlighting the $ref resolution behavior, 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 says 'Use this when you need the complete endpoint definition in a single call, without needing to follow $ref links manually' and provides concrete examples of when to use it. It contrasts with swagger_get_endpoint, effectively guiding selection between alternatives.

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, and the description adds an Error Handling section stating that an error is returned if the spec name has not been loaded. It also provides the full return structure. 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?

The description is well-organized into Args, Returns, Examples, and Error Handling sections, with the main purpose stated first. It is slightly verbose for a one-parameter tool, but every section earns its place by providing concrete guidance and examples.

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 info tool, the description covers purpose, return format, parameter prerequisite, and error behavior. The annotations cover the safety profile. Given the tool's low complexity, there are no significant gaps.

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 single parameter `spec_name` is fully described in the schema (100% coverage), and the description's Args section repeats the schema description verbatim, adding no new semantic meaning. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource ('Get general information about a loaded OpenAPI/Swagger specification') and lists key fields, clearly distinguishing it from sibling tools that drill into endpoints, schemas, or paths. The phrase 'high-level summary' reinforces its distinct role.

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

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

It explicitly states 'Use this tool to get a high-level summary of an API spec' and provides two example user intents ('Tell me about this API', 'What's the base URL'). It also links to the sibling tool `swagger_list_loaded` for finding available spec names. However, it does not mention alternatives for endpoint-specific info or explicitly say when not to use it, so a 4 rather than 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 set readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: error handling for unloaded specs and missing schemas with suggestions, and the return format ('full schema definition including type, properties, required fields, enums, constraints, and examples'). This goes beyond what annotations stipulate.

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 well-structured with clear sections (overview, usage, args, returns, examples, error handling). While it's a bit longer than strictly necessary, every section adds useful context and it's front-loaded with the core purpose.

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 2-param tool with no output schema, the description covers purpose, when to use, what it returns, and error cases. The 'formatted output' is vague, but the overall coverage is strong, making it adequately complete for an agent.

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 detailed descriptions for both parameters, including examples and case-sensitivity. The description repeats the parameter names in Args without adding significant new meaning; its examples show usage patterns but don't enhance semantic understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Get detailed information about a specific component schema (data model), including all properties, types, constraints, and examples.' This specific verb+resource distinguishes it from sibling tools like swagger_list_schemas (which lists) and swagger_get_endpoint (which handles endpoints).

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 explicit workflow guidance: 'Use this tool to drill down into a specific data model after using swagger_list_schemas.' It also includes natural-language examples showing when to use it. It doesn't explicitly exclude alternatives, but the context is clear.

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. The description adds context that the specs are 'in memory' and 'currently loaded', and includes the return structure with fields. This exceeds the annotation baseline.

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 well-structured with a summary, use cases, args, return format, and examples. Each section serves a purpose with no redundancy or filler.

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

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

For a zero-parameter tool, the description is fully complete: it explains what it lists, includes a return structure example, and provides usage examples. There is no missing information that the agent would need.

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 zero parameters and coverage is 100%. The description explicitly states 'Args: None' and repeats it in examples, which reinforces that no parameters are needed. This is a clear, minimal case with no ambiguity.

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 action ('List') and resource ('currently loaded OpenAPI/Swagger specifications in memory'). It is distinct from sibling tools like swagger_load_spec or swagger_list_tags, which have different purposes.

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 use cases ('What specs have I loaded?') and notes when no parameters are needed. It does not explicitly exclude alternatives, but the context is sufficient for an agent to understand when this tool is 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is clear. The description adds value by disclosing error behavior ('Returns error if the spec name has not been loaded yet') and pagination details (has_more, next_offset). It does not cover all nuances, but it meaningfully supplements the 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 well-organized with clear sections (summary, args, returns, examples, error handling), but it duplicates the schema's parameter documentation in the 'Args' block, adding redundancy. The first sentence effectively front-loads the purpose, yet the repeated descriptions make it longer than necessary.

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 four parameters and no output schema, the description is remarkably complete. It includes a detailed return structure, pagination semantics, examples, and error handling. It also implies a prerequisite (spec must be loaded) and guides progressive exploration. No critical missing context for an agent to invoke and interpret results.

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 all four parameters well-documented in the input schema. The description adds value through concrete usage examples and by reinforcing cross-references to sibling tools (e.g., 'use swagger_list_tags to see available tags' in the schema, which is echoed in the description). The Args section mostly duplicates schema, but the examples and error handling enrich parameter understanding.

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's function: 'List all API endpoints (paths and HTTP methods) from a loaded OpenAPI spec, optionally filtered by tag.' This clearly distinguishes it from sibling tools like swagger_list_tags, swagger_get_endpoint, and swagger_search. The scope and filter capability are specified upfront.

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 usage context: 'Use this tool to get a high-level overview of all available API operations' and suggests filtering for 'progressive exploration.' It gives concrete examples for when to use the tool with and without a tag. However, it does not explicitly state when not to use it or mention alternative tools for detailed endpoints, though the sibling names hint at these alternatives.

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 and idempotentHint, and the description adds valuable behavioral details: the return payload structure, pagination semantics (limit, offset, has_more, next_offset), and error handling if the spec name is not loaded. This goes beyond 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 well-structured with sections for Args, Returns, Examples, and Error Handling. It is slightly redundant with the schema for parameter descriptions, but the additional return format and examples justify the length.

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, but the description covers the purpose, usage, parameters, return format, pagination, and error handling. Combined with strong annotations, this provides complete contextual guidance for an agent.

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 covers all three parameters with complete descriptions (100% coverage), so the description adds little beyond that. The 'Args' section restates schema information, and the examples provide usage context but not deeper parameter semantics.

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

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

The description uses the specific verb 'List' with the resource 'all component schemas (data models) defined in the loaded OpenAPI spec', clearly distinguishing it from siblings like swagger_get_schema. The scope is 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?

It provides clear when-to-use examples ('What data models are defined?') and states the tool is for getting an overview of all data models. However, it does not explicitly mention alternatives or when not to use it, so it 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=true and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: it requires a previously loaded spec, returns an error if the spec isn't loaded, and lists the return structure with endpoint counts. This goes beyond the annotations but doesn't dive into deeper behaviors like pagination or rate limits.

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

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

The description is well-structured and front-loaded with the tool's purpose. It includes concise sections for args, return format, examples, and error handling, with no wasted words. Every section 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 list tool with one parameter, the description is comprehensive: it covers the input source, the return structure, and the error condition. The absence of an output schema is mitigated by the explicit return example in the description. Combined with rich annotations, this is fully 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?

Schema description coverage is 100% and the schema already explains spec_name and points to swagger_list_loaded for available names. The description's 'Args' section simply restates the parameter without adding new semantic detail, so it provides little value beyond the schema.

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

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

The description clearly states the verb and resource: 'List all API tags/groups and their associated endpoint counts from a loaded OpenAPI spec.' This is specific and distinguishes it from sibling tools like swagger_list_paths or swagger_list_schemas, which target different aspects of the spec.

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 'Use when' examples such as 'What tags/groups are available?' and 'How are the endpoints organized?', which clarify when to use this tool. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of full exclusionary 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 indicate readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral detail: it stores the spec in memory, assigns a unique name with numeric suffix for duplicates, and lists exact error conditions. This goes beyond the structured annotations and gives the agent a clear model of side effects and edge cases.

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 well-organized with a clear first sentence, then sections for Args, Returns, Examples, and Error Handling. Every sentence adds necessary information, and there is no filler or redundancy. It is appropriately detailed for a tool that lacks an output schema.

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

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

With only one parameter and no output schema, the description fully compensates by detailing the return object's fields with descriptions, explaining naming behavior, and enumerating error scenarios. This makes the tool's behavior fully predictable and self-contained for an agent.

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 file_path with 100% coverage, so the baseline is 3. The description enhances this by providing example path formats ('./swagger.doc.json' vs '/absolute/path/to/spec.json') and explaining that paths can be relative or absolute, giving the agent practical guidance beyond the schema.

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

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

The description begins with 'Load and parse an OpenAPI (Swagger) specification document from a local JSON file,' which uses a specific verb and resource. It clearly distinguishes from sibling tools by emphasizing 'local JSON file' and contrasting with the broader swagger_load_spec context.

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 use-case examples ('Use when: Load the local swagger.doc.json') and states that the path can be absolute or relative, which clarifies when to invoke this tool. However, it does not explicitly mention when not to use it or directly reference alternative tools like swagger_load_spec for remote URLs.

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 annotations (readOnlyHint, destructiveHint), the description explains in-memory storage, unique name assignment with numeric suffix for duplicates, and error behavior for unreachable URLs, invalid JSON, and unsupported YAML. This adds meaningful behavioral context.

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 well-structured with clear sections (Args, Returns, Examples, Error Handling) and front-loaded with a one-sentence summary. While detailed, every section adds necessary information for a tool that is a prerequisite for all others.

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 provides a complete return object schema, explains the tool's role in the overall workflow, and covers likely failure modes. Since there is no output schema, this level of detail is necessary and fully provided.

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 input schema (100% coverage) with examples and usage notes. The description duplicates these details but does not significantly add to parameter semantics beyond what the schema provides, 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 uses a specific verb ('Load and parse') with a clear resource ('OpenAPI/Swagger specification document from a URL'), and the sibling context (e.g., swagger_load_local_spec) shows this tool is the URL-based loader. This clearly distinguishes it from siblings that list tags/paths or load local specs.

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 'You must load a spec before using any other tools,' providing a mandatory usage context. It also covers when auth_header is needed and gives examples for common requests, though it doesn't explicitly mention swagger_load_local_spec as an alternative—the URL-vs-local distinction is implied by the tool name and description.

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

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

Annotations already mark destructiveHint=true, and the description adds meaningful context by specifying the in-memory nature of the removal, the confirmation message returned, and the error case for missing spec names. This goes beyond the raw annotation without contradicting it.

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 well-structured with a front-loaded action statement followed by usage, args, returns, examples, and error handling. The examples are useful, though the Args section somewhat redundantly repeats the schema 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 one-parameter destructive tool without an output schema, the description covers purpose, usage scenarios, return type, and error handling. It does not explicitly address reversibility, but the reload workflow implies it, making it sufficiently 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 fully describes the single parameter 'spec_name' and points to swagger_list_loaded for available names. The description's Args section and examples add some practical context, but do not significantly extend the schema's semantic 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 opens with a specific action 'Remove a loaded OpenAPI/Swagger specification from memory', clearly identifying both the verb and the resource. This distinguishes it from sibling tools like swagger_load_spec and swagger_list_loaded, and the concrete examples further solidify the intent.

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 use cases: 'free up memory or reload a spec that has changed', which gives clear context for when to invoke this tool. It does not explicitly name alternatives, but the reload workflow implies removing before loading, which is sufficient 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 the tool read-only and idempotent. The description goes further by detailing the search scope (paths, summaries, tags, etc.), the exact return JSON structure, and error behavior for unloaded specs, giving agents a complete behavioral picture.

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 well-structured with clear sections (summary, search scope, Args, Returns, Examples, Error Handling) and front-loaded with the core purpose. The detailed return schema and examples justify the length, with no significant 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?

Despite lacking an output schema, the description fully specifies the return format, error handling, and usage examples. The search scope is comprehensive, and the 100% parameter schema and read-only annotations cover the remaining context. Nothing critical 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?

Both parameters are already fully described in the schema (100% coverage), including a cross-reference to swagger_list_loaded for spec names. The description's Args section largely restates this information without adding meaningful new parameter semantics, so the baseline score 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 opens with 'Search across all endpoints and schemas in a loaded OpenAPI spec', clearly stating a specific verb (search) and resource (endpoints and schemas). It also enumerates the exact fields searched (paths, summaries, operationIds, etc.), making it distinct from sibling list/get/load 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?

Provides explicit 'Use when' examples ('Search for anything about pets' → query='pet') that clarify intended scenarios. It doesn't explicitly exclude alternatives like swagger_list_paths, but the search context is well established.

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