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

The readOnlyHint annotation already signals a safe read operation. The description adds useful behavioral context by stating that it 'dynamically extracts service information from CDK constructs without relying on hardcoded service mappings,' explaining its methodology beyond what annotations provide.

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

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

The description is two short sentences, front-loaded with the primary purpose, and contains no redundant wording. Every sentence contributes useful 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?

With one well-documented parameter, a readOnly annotation, and an output schema, the description provides enough information for correct invocation. It covers the tool's purpose and operational approach without needing to explain return values thanks to 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 only parameter, project_path, is fully documented in the schema as 'Path to the project directory.' The description does not add additional meaning about the parameter, so the baseline of 3 for high schema coverage 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 a specific verb 'Analyze' and clear resource 'CDK project', and states the actionable outcome 'identify AWS services used.' It distinguishes itself from the sibling 'analyze_terraform_project' by the project 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 clearly indicates use for CDK projects, which gives context for when to select it. However, it does not explicitly mention alternatives like 'analyze_terraform_project' or state when not to use this tool.

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

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

The readOnlyHint annotation already declares the tool as read-only. The description adds valuable behavioral context by noting that the tool 'dynamically extracts service information from Terraform resource declarations', which explains how the analysis works and what data sources are used. This goes beyond the annotation's safety declaration and informs the agent about the tool's operational mechanism.

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

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

The description is two sentences long, with no redundant phrasing. The first sentence states the primary purpose, and the second adds a key behavioral detail. It is front-loaded and every word contributes value.

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

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

The tool has a single parameter, an output schema, and a readOnly annotation. The description sufficiently explains the tool's purpose and behavior without needing to detail return values, as the output schema likely covers that. It is complete for the tool's simplicity, though it could mention potential limitations (e.g., only works with Terraform source files), but this is not a critical omission.

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

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

The schema has one parameter with a description ('Path to the project directory') and 100% coverage. The tool description adds specificity by clarifying that the path points to a Terraform project, which is not explicit in the parameter's generic wording. This helps the agent infer the expected input format and purpose.

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 analyzes a Terraform project to identify AWS services used, using the specific verb 'analyze' with the resource 'Terraform project' and the outcome 'identify AWS services'. This distinguishes it from sibling tools like analyze_cdk_project, which targets CDK projects.

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 when the user has a Terraform project, but it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or prerequisites. The existence of sibling analyze_cdk_project suggests a need for differentiation, but the description relies on the tool name and the word 'Terraform' to imply 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?

Annotations declare readOnlyHint=true, and the description is consistent. It adds behavioral expectations: ALWAYS include unit pricing, calculation breakdowns, pricing model, assumptions, and exclusions. It also discloses output format options. This goes beyond the annotation.

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 long, but front-loaded with a clear purpose and requirements, followed by structured sections and a comprehensive example. It earns its length for a 10-parameter tool, though the example is quite verbose.

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 complex tool with 10 parameters, nested objects, and an output schema, the description covers required input structure, output formats, report content requirements, and example usage. It omits return-value details, but the presence of an output schema reduces that burden.

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%, but the description substantially enriches parameter semantics with a full JSON example showing the structure of pricing_data, detailed_cost_data, recommendations, and other parameters. It clarifies how pricing_data from get_pricing should be passed and the relationships between fields.

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 opening sentence uses a specific verb ('Generate') and resource ('cost analysis report') and clarifies the tool's scope (based on pricing data for one or more AWS services). This clearly distinguishes it from siblings that retrieve pricing or analyze projects.

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 states the prerequisite ('This tool requires AWS pricing data') and provides an example showing pricing_data retrieved from get_pricing, implying a workflow. However, it doesn't explicitly name alternatives or state when not to use it, so it falls short of full guidance.

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

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

The description aligns with the readOnlyHint annotation, presenting a 'Get' operation. It does not contradict the annotation. However, it adds only content details (component relationships, cost considerations) and does not disclose other behavioral traits like authentication needs or rate limits, but the annotation already indicates a safe read operation.

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

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

The description is a single front-loaded sentence with no wasted words. It clearly states what the tool does and includes two key content categories without unnecessary elaboration.

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

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

For a simple read-only tool with no parameters and an output schema, the description provides complete context: it identifies the resource, content area, and relevant considerations. The output schema covers return structure, so the description need not detail 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 schema shows zero parameters, so there is no parameter information to add. The description mentions the scope ('architecture patterns for Amazon Bedrock applications') which implicitly defines the parameter domain, but with 0 parameters the baseline of 4 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 states a specific verb and resource: 'Get architecture patterns for Amazon Bedrock applications', and mentions specific contents (component relationships and cost considerations). This clearly distinguishes it from sibling tools like get_pricing or analyze_cdk_project.

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 purpose implies when to use the tool, but the description does not provide explicit guidance or mention alternatives like the pricing or CDK/Terraform analysis tools. No exclusions or when-not-to-use instructions are given.

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 provide readOnlyHint=true, and the description aligns with that while adding substantial behavioral context: return format (dictionary with 'csv' and 'json' keys), default effective_date behavior, and CSV file processing quirks (metadata lines, header location, grep example). However, it mentions an 'optional effective_date' parameter that does not appear in the schema, which slightly undermines accuracy.

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?

Well-organized with clear headings (PURPOSE, WORKFLOW, PARAMETERS, RETURNS, USE CASES, FILE PROCESSING) and front-loaded purpose. Every section delivers actionable information without fluff, making the length appropriate for the tool's complexity.

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?

Description covers purpose, workflow alternatives, parameter usage, return structure, use cases, and file processing details. Combined with the output schema and readOnlyHint annotation, it gives an agent everything needed to invoke the tool correctly and process 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 already covers both parameters with clear descriptions (100% coverage). The description adds value by pointing to get_pricing_service_codes for valid service codes and providing region examples, but it also documents a non-existent 'effective_date' parameter, creating a mismatch between description and schema. Thus, baseline 3 with a minor penalty for the misleading addition.

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?

Description opens with a specific verb+resource phrase ('Get download URLs for bulk pricing data files'), immediately distinguishing this tool from siblings like get_pricing (current pricing) and the service code listing tools. It clearly identifies the deliverable (download URLs) and the intended scope (bulk/historical data).

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

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

Explicitly states when to use this tool: historical pricing analysis or bulk data processing 'when current pricing from get_pricing() isn't sufficient.' It also names an alternative (get_pricing) and refers to get_pricing_service_codes for valid inputs, providing clear guidance on tool selection.

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

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

While annotations already declare readOnlyHint=true, the description adds substantial behavioral context beyond that: character limits, region auto-filtering, limitations on spot/savings plans, the 1024-character ANY_OF limit, and the behavior of output_options for size reduction. This exceeds what annotations provide and covers critical operational details.

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

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

The description is extremely long and contains redundancy (e.g., repeated emphasis on exhaustive enumeration and exclude_free_products). While it is well-structured with clear sections and front-loaded summary, it could be significantly trimmed without losing important information. The length may overwhelm agents, despite the effective use of code examples and bullet points.

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 (7 parameters, nested filter objects, output_options transformation), the description covers all necessary context: discovery workflow, filter construction, output size control, constraints, anti-patterns, and success criteria. The output schema provides return structure, so the description appropriately focuses on methodology and edge cases.

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%, but the description goes far beyond the schema. It explains filter types in detail (EQUALS, ANY_OF, CONTAINS, NONE_OF), the meaning of the output_options fields, the max_allowed_characters semantics, and provides concrete examples of valid filter structures and discovery workflows. This adds significant value beyond parameter names and default values.

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 identifies the tool's purpose: 'Get detailed pricing information from AWS Price List API with optional filters.' It uses a specific verb+resource combination and differentiates from siblings like get_pricing_service_codes and get_pricing_attribute_values, which serve the discovery workflow.

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

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

Usage guidelines are exceptionally explicit: a mandatory discovery workflow, common use cases (cost optimization, multi-region comparison), anti-patterns, and filtering strategies. It also names alternatives like get_price_list_urls for historical data and explicitly states when to skip discovery steps.

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 convey readOnlyHint=true, so the description only needs to add extra behavioral context. It does so by disclosing the 'all-or-nothing' error handling and explaining how filters partially apply (e.g., 'filters applies only to instanceType, location returns all values'). This goes beyond the annotation and is valuable for predicting tool behavior.

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

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

The description is well-structured with clear sections (PURPOSE, WORKFLOW, PARAMETERS, RETURNS, etc.) and front-loads the core purpose. It is somewhat lengthy and repeats some schema content, but every section adds useful context such as error handling and examples, so the length is justified.

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 moderate complexity, the description covers all essential aspects: purpose, workflow, parameter usage, return format, error handling, and examples. It also includes an example return structure, making it fully self-contained for an agent to understand invocation and expected output.

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 provides 100% parameter descriptions, so the baseline is 3. The description adds value by including concrete examples for each parameter, clarifying the 'filters' behavior with regex patterns, and explaining the region default and its importance for matching get_pricing() queries. This enriches the semantics beyond the schema fields.

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 'Get valid values for pricing filter attributes,' which is a specific verb and resource. It clearly distinguishes from sibling tools by noting it is used after get_pricing_service_attributes() to discover valid values, whereas get_pricing_service_attributes returns attribute names themselves.

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 workflow context: 'Use this after get_pricing_service_attributes()' and 'Use these values in get_pricing() filters.' It also advises setting the region to match the region used in get_pricing(). However, it does not explicitly state when not to use this tool or mention alternative tools for different scenarios, so it lacks a full when/when-not structure.

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

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

Annotations declare readOnlyHint=true, and the description adds context about default region behavior (AWS_REGION env var), case-insensitive regex filtering, and return value format (list of attribute names). This goes beyond the annotation without contradicting it, though it doesn't discuss edge cases like empty results or error handling.

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 headers (PURPOSE, WORKFLOW, PARAMETERS, RETURNS, NEXT STEPS, EXAMPLE). Every section adds value, and the purpose is front-loaded in the first sentence. No filler or redundancy.

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

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

Given the tool's moderate complexity, the description covers purpose, parameters, return values, usage order relative to sibling tools, and an example. Even with an output schema present, it explains what the return data looks like ('List of attribute names'), making it self-contained.

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 examples for service_code ('AmazonEC2', 'AmazonRDS'), explains the region parameter's default and why it matters, and illustrates the filter regex with examples. This enriches the schema descriptions meaningfully.

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 filterable attributes available for an AWS service in the Pricing API.' It clearly distinguishes itself from siblings by focusing on filterable attributes, and the workflow section explicitly contrasts with get_pricing_service_codes and get_pricing_attribute_values.

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

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

The description provides explicit workflow guidance: 'Use this after get_pricing_service_codes()' and instructs to use get_pricing_attribute_values() next. It also tells users to match the region to get_pricing(), giving clear when-to-use and alternative paths.

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, establishing the tool is safe. The description adds valuable behavioral context: it returns a list of service codes, notes that service codes may differ from AWS console names (with examples), and explains filter behavior. This exceeds the bar set by the calibration example get_calls, which only added date-range scope. No contradictions with annotations.

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

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

The description is well-structured with clear sections (PURPOSE, PARAMETERS, WORKFLOW, RETURNS, NEXT STEPS, NOTE). It is front-loaded with the primary purpose. Every section adds value: the NOTE about naming differences prevents common mistakes, while NEXT STEPS guides further action. Despite being longer than typical, it is appropriately sized for the tool's discovery role.

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 (1 optional param) and has a documented output schema, but the description goes beyond minimal requirements by explaining the return values, providing usage workflow, and listing sibling tools to use next. It is self-contained for an agent to correctly invoke and interpret the result. The output schema exists, so return-detail explanation is optional, but the description still covers it redundantly.

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

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

The schema covers 100% of the parameter, but the description enhances understanding with a concrete example: '"bedrock" matches "AmazonBedrock", "AmazonBedrockService"'. This demonstrates regex case-insensitivity and partial matching, which the schema's brief description does not convey. The description also clarifies that the filter is optional, reinforcing the schema's default null.

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

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

The description clearly states the tool's purpose: 'Get AWS service codes available in the Price List API.' It uses a specific verb ('Get') and resource ('AWS service codes'), and distinguishes itself from siblings like get_pricing (which retrieves actual pricing data) and get_pricing_service_attributes (which gets filters). This makes the tool's role 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?

Explicitly states when to use: 'This is the starting point for any pricing query. Use this first to find the correct service code.' It also names alternatives in NEXT STEPS: use get_pricing_service_attributes() for filters and get_pricing() for actual pricing data. This provides clear when-to-use and when-to-move-on guidance.

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