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

With no annotations, the description discloses the HTTP method (GET), return format (JSON string), and error handling (returns error information). The <important> prerequisite also adds context about required prior steps. It does not mention auth or rate limits, but the prerequisite likely covers that.

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 compact and front-loaded, with an <important> block immediately stating the prerequisite, followed by a one-sentence description and a simple Args/Returns structure. Every sentence earns its place with no 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 tool with one parameter and simple GET behavior, the description covers purpose, parameter usage, return value, and the required prerequisite. The presence of an output schema further reduces the need to explain return structure, though the description already says it returns a JSON string.

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 explains the 'path' parameter with examples ('/cc-ui/v1/stacks/my-stack' or 'cc-ui/v1/stacks'), adding format and context beyond the schema's bare string type. Since schema description coverage is 0%, this fully compensates for the missing parameter documentation.

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 makes a GET request to the Facets Control Plane API, specifying the verb (GET) and resource (Control Plane API). It also includes a prerequisite hint, distinguishing it from sibling catalog/search 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 gives a clear prerequisite: 'Make sure you have Called FIRST_STEP_get_api_script_guide first before this tool.' This implies when to use the tool (after obtaining the guide) and differentiates it from catalog/search tools, though it does not explicitly mention alternatives or 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?

With no annotations provided, the description carries the burden of explaining behavior. It states that the tool returns 'a JSON string containing the content of the API script guide,' which is the core expected behavior. It does not explicitly discuss side effects, but for a guide-loading tool, none are expected. This is more informative than a bare 'get guide' description.

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 highly concise and effectively front-loaded. It begins with a vital directive in a highlighted <important> tag, then gives a one-sentence purpose, and finishes with a clear return type. 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 simplicity (no parameters, returns a string), the description is fully complete. It specifies the return format and the mandatory first-call position in the workflow. The sibling tools are all different, and no additional context 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 tool has zero parameters, so the baseline is 4. The input schema is empty and thus requires no additional explanation. The description appropriately focuses on the return value rather than parameters.

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 'Loads the API script generation guide' and explains what the guide contains (comprehensive instructions for creating scripts that interact with Control Plane APIs). The verb 'loads' and specific resource make it distinct from sibling tools that search or call APIs.

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 instructs the agent to 'ALWAYS Call this tool first before calling any other tool of this mcp.' This strong, unambiguous usage guidance leaves no doubt about when and how to use the tool in the 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?

Given no annotations exist, the description carries the behavioral transparency burden. It discloses the return type as 'JSON string containing the complete operation details or null if not found,' which informs the agent about output and failure behavior. The mandatory prerequisite step is also a behavioral trait. However, it does not explicitly state that the operation is read-only or free of side effects, though 'load' implies this.

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: a bolded prerequisite, a one-line purpose, and concise Args/Returns documentation. Every sentence contributes necessary information without redundancy. The format is easy to parse and front-loads the critical prerequisite.

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 load tool, the description covers all necessary context: prerequisite, function, parameter semantics, return format, and null case. The existence of an output schema means the return structure need not be explained further. The description is complete given the tool's simplicity and available metadata.

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 only specifies `operation_id` with type and title, lacking any description (0% coverage). The description compensates by providing an Args block explaining 'The unique operation ID to load.' This adds essential meaning beyond the schema, clarifying the nature and purpose of the parameter.

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: 'Load a specific operation by its operationId.' It uses a specific verb 'Load' and identifies the resource (operation) and the key identifier (operationId). This distinguishes it from sibling 'load_api_operation_by_path_and_method', which uses a different identification scheme.

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 explicit usage guidance by mandating 'Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool.' This establishes a clear precondition and ordering. It does not explicitly mention alternatives or exclusions, but the prerequisite and phrasing imply it is used when an operationId is known and one needs the full operation 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?

No annotations are provided, so the description carries the full burden. It discloses the return behavior ('JSON string containing the complete operation details or null if not found') and the prerequisite dependency. However, it does not explicitly state that the operation is read-only, nor does it cover edge behaviors like authentication or error states. This is adequate but minimal for a non-annotated 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 succinct, with a highlighted <important> precondition, then a one-sentence purpose, and clearly separated Args and Returns sections. No extraneous content.

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 (2 params, no nested objects), and the description covers purpose, parameters, return type, and the prerequisite call. The output schema is present so return values need not be over-explained. Lacks explicit comparison to sibling load_api_operation_by_operationId, but overall it is sufficient for an agent to invoke it correctly.

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

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

The schema provides only type strings with no descriptions (0% coverage). The description compensates by giving a concrete path example and an explicit list of HTTP methods, adding practical meaning to both parameters.

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 'Load a specific operation by its path and HTTP method' with a concrete example path. The name and description clearly distinguish it from the sibling load_api_operation_by_operationId which loads by operationId.

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 includes an explicit prerequisite: 'Make sure you have Called FIRST_STEP_get_api_script_guide first before this tool.' This gives clear context for when the tool can be used. It does not explicitly mention when to use this tool vs alternatives, but the method of selection is self-evident from the name and sibling 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?

With no annotations provided, the description carries the burden of transparency. It discloses the return behavior (JSON string or null if not found) and the prerequisite. However, it does not explicitly state whether the operation is read-only or describe any side effects, which is a notable gap for a tool with no 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 an important note, an Args section, and a Returns section. The important note is essential but styled with an HTML-like tag that adds visual noise. Overall, every sentence earns its place and the content is appropriately sized.

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

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

For a simple tool with one parameter and no annotations, the description is fairly complete. It explains the prerequisite, parameter semantics, and return format. The output schema exists, so detailed return values are not required, but the description still summarizes the return behavior adequately.

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 parameter schema has no description coverage (0%), but the description fully compensates by explaining schema_name as 'The name of the schema to load (e.g., 'Stack', 'ErrorDetails')'. This provides type, meaning, and concrete examples, adding clear value beyond the bare 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 'Load a specific schema by its name,' with a specific verb and resource. It distinguishes itself from sibling tools like load_api_operation_by_operationId, as it targets schemas rather than operations. The tool name and description align well.

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 an explicit prerequisite: 'Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool.' This gives clear context for when to use the tool. However, it does not explicitly mention alternatives or when not to use it, so it lacks 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?

With no annotations, the description carries the full burden. It discloses the refresh action, the fetching of the latest OpenAPI specification, and the return of a success message. However, it omits potential side effects like overwriting existing catalog data and failure modes if the prerequisite is not met, leaving some behavioral gaps.

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 front-loaded with an important prerequisite instruction. Every sentence contributes meaning, and the structure is clear 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?

For a zero-parameter tool, the description covers the action, return value, and a key prerequisite, which is largely complete. It could improve by mentioning error cases or side effects, but given the simplicity of the tool, it is sufficiently contextualized.

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 description does not need to explain parameter semantics. The baseline for zero-param tools is 4, and no additional parameter information is required.

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 refreshes the API catalog by fetching the latest OpenAPI specification. This is a specific verb+resource and distinguishes it from sibling tools that search or load API operations/schemas.

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

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

The description explicitly instructs that FIRST_STEP_get_api_script_guide must be called first, establishing a clear prerequisite context. However, it does not mention when not to use this tool or provide alternative options, which prevents 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?

With no annotations provided, the description carries the full burden. It discloses the fuzzy matching behavior, the restriction to active operations, and the return format (JSON string). It does not mention error handling or no-result behavior, but covers the core behavioral traits for a search 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 concise and well-structured: a prominent prerequisite warning, a clear purpose sentence, a note about active operations, and an Args/Returns section. 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?

Given the tool's simplicity (one parameter) and the presence of an output schema, the description provides sufficient context: prerequisite, search scope, active-operation filter, and return format. It could mention how to interpret the returned JSON, but that is likely covered by the output schema.

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 only lists 'query' with no description (0% coverage). The description compensates fully by explaining that the query matches operation summaries, descriptions, tags, and operation IDs, adding meaningful semantic context beyond the schema itself.

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 'Search for operations across the OpenAPI specification using fuzzy matching,' combining a specific verb (search), resource (operations), and scope. It distinguishes from sibling tools like search_api_schemas and load_api_operation_by_operationId by focusing on cross-specification search rather than schema lookup or direct loading.

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 requires calling FIRST_STEP_get_api_script_guide first, giving a clear usage prerequisite. It also notes the restriction to active (non-deprecated) operations, which sets an important boundary. However, it does not explicitly compare against alternative search/load tools, so it falls short of full when/when-not guidance.

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

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

There are no annotations, so the description carries the full disclosure burden. It discloses the fuzzy matching behavior and the return format as a JSON string. However, it does not explicitly state read-only status, permissions, or failure behavior if the prerequisite is not met, leaving some gaps.

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 well-structured: it opens with an important prerequisite, then a one-sentence purpose, followed by Args and Returns sections. No redundancy or unnecessary details are present.

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 and an output schema, the description covers the key aspects: purpose, prerequisite, parameter semantics, and return type. However, it lacks explicit information about the tool's non-mutating nature or limitations, so it is not 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?

The input schema has no description for the 'query' parameter, but the description compensates fully by stating: 'query (str): Search query to match against schema names and descriptions.' This clearly explains the parameter's meaning and target.

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: 'Search for schemas across the OpenAPI specification using fuzzy matching.' This uses a specific verb (search) and resource (schemas), and the presence of the sibling tool search_api_operations indicates differentiation by resource type.

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 includes a clear prerequisite, 'Make Sure you have Called FIRST_STEP_get_api_script_guide first before this tool,' which provides context for when to use it. However, it does not explicitly mention alternatives or exclusions, such as noting that search_api_operations should be used for operations.

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