Integrates with Amazon SageMaker to validate workloads against the AWS Well-Architected Framework across all six pillars (Security, Reliability, Performance Efficiency, Cost Optimization, Operational Excellence, Sustainability). Provides tools to check endpoints, training jobs, notebook instances, and models, returning findings with severity levels and actionable recommendations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Amazon SageMaker Well-Architected MCP Server Validate my SageMaker endpoint for reliability"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The Amazon SageMaker Well-Architected MCP server provides agents with tools to validate SageMaker workloads against all six AWS Well-Architected Framework pillars: Security, Reliability, Performance Efficiency, Cost Optimization, Operational Excellence, and Sustainability.
Provides comprehensive tools for validating SageMaker resources (endpoints, training jobs, notebook instances, and models) against AWS best practices across all six Well-Architected pillars. Each validation returns findings with severity levels and actionable recommendations. See the validators documentation for detailed information on the supported tools.
Related MCP server: AWS CDK MCP Server
This quickstart guide walks you through the steps to configure the Amazon SageMaker Well-Architected MCP Server for use with Kiro, Cursor, and other compatible IDEs.
Kiro | Cursor | VS Code |
|
|
Set up Kiro
See the Kiro IDE documentation or the Kiro CLI documentation for details.
For global configuration, edit ~/.kiro/settings/mcp.json. For project-specific configuration, edit .kiro/settings/mcp.json in your project directory.
The example below includes the --allow-sensitive-data-access flag for accessing detailed resource configurations:
For Mac/Linux:
```
{
"mcpServers": {
"awslabs.sagemaker-wa-mcp-server": {
"command": "uvx",
"args": [
"awslabs.sagemaker-wa-mcp-server@latest",
"--allow-sensitive-data-access"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
},
"autoApprove": [],
"disabled": false
}
}
}
```For Windows:
```
{
"mcpServers": {
"awslabs.sagemaker-wa-mcp-server": {
"command": "uvx",
"args": [
"--from",
"awslabs.sagemaker-wa-mcp-server@latest",
"awslabs.sagemaker-wa-mcp-server.exe",
"--allow-sensitive-data-access"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
},
"autoApprove": [],
"disabled": false
}
}
}
```Verify your setup by running the /tools command in the Kiro CLI to see the available SageMaker Well-Architected MCP tools.
This server provides comprehensive Well-Architected validation for SageMaker workloads with 51 checks across all six pillars. For broader AWS API access and documentation lookup, you can also use AWS API MCP Server and AWS Documentation MCP Server.
The args field in the MCP server definition specifies the command-line arguments passed to the server when it starts. These arguments control how the server is executed and configured. For example:
For Mac/Linux:
{
"mcpServers": {
"awslabs.sagemaker-wa-mcp-server": {
"command": "uvx",
"args": [
"awslabs.sagemaker-wa-mcp-server@latest",
"--allow-sensitive-data-access"
],
"env": {
"AWS_PROFILE": "your-profile",
"AWS_REGION": "us-east-1"
}
}
}
}For Windows:
{
"mcpServers": {
"awslabs.sagemaker-wa-mcp-server": {
"command": "uvx",
"args": [
"--from",
"awslabs.sagemaker-wa-mcp-server@latest",
"awslabs.sagemaker-wa-mcp-server.exe",
"--allow-sensitive-data-access"
],
"env": {
"AWS_PROFILE": "your-profile",
"AWS_REGION": "us-east-1"
}
}
}
}The command format differs between operating systems:
For Mac/Linux:
awslabs.sagemaker-wa-mcp-server@latest - Specifies the latest package/version specifier for the MCP client config.
For Windows:
--from awslabs.sagemaker-wa-mcp-server@latest awslabs.sagemaker-wa-mcp-server.exe - Windows requires the --from flag to specify the package and the .exe extension.
--allow-sensitive-data-access (optional)Enables access to sensitive data such as detailed resource configurations, tags, and endpoint config details. This flag is required for tools that access potentially sensitive information.
Default: true (Access to sensitive data is allowed by default)
Example: remove --allow-sensitive-data-access from the args list in your MCP server definition to disable it.
The env field in the MCP server definition allows you to configure environment variables that control the behavior of the SageMaker Well-Architected MCP server. For example:
{
"mcpServers": {
"awslabs.sagemaker-wa-mcp-server": {
"env": {
"FASTMCP_LOG_LEVEL": "ERROR",
"AWS_PROFILE": "my-profile",
"AWS_REGION": "us-west-2"
}
}
}
}FASTMCP_LOG_LEVEL (optional)Sets the logging level verbosity for the server.
Valid values: "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
Default: "WARNING"
Example: "FASTMCP_LOG_LEVEL": "ERROR"
AWS_PROFILE (optional)Specifies the AWS profile to use for authentication.
Default: None (If not set, uses default AWS credentials).
Example: "AWS_PROFILE": "my-profile"
AWS_REGION (optional)Specifies the AWS region where SageMaker resources are validated, which will be used for all AWS service operations.
Default: None (If not set, uses default AWS region).
Example: "AWS_REGION": "us-west-2"
The SageMaker Well-Architected MCP Server implements the following security features:
AWS Authentication: Uses AWS credentials from the environment for secure authentication.
SSL Verification: Enforces SSL verification for all AWS API calls.
Least Privilege: Only requires read/describe/list permissions on SageMaker resources.
User Agent Tracking: All API calls include a custom user agent for auditability.
When using the SageMaker Well-Architected MCP Server, consider the following:
AWS Credentials: The server needs permission to describe and list SageMaker resources.
Network Security: Ensure the environment running the server has network access to AWS APIs.
Authentication: Use appropriate authentication mechanisms for AWS resources.
Authorization: Configure IAM with read-only SageMaker permissions.
Data Protection: Resource configurations may contain sensitive information.
Logging and Monitoring: Enable logging and monitoring for SageMaker resources.
The SageMaker Well-Architected MCP Server performs only read-only operations, which is recommended and considered generally safe for production environments. Below are the tools available:
Read-only mode (default): validate_sagemaker_resource, validate_all_endpoints, list_sagemaker_resources, get_pillar_details.
autoApprove (optional)An array within the MCP server definition that lists tool names to be automatically approved by the MCP Server client, bypassing user confirmation for those specific tools. Since all operations are read-only, auto-approving all tools is safe. For example:
For Mac/Linux:
{
"mcpServers": {
"awslabs.sagemaker-wa-mcp-server": {
"command": "uvx",
"args": [
"awslabs.sagemaker-wa-mcp-server@latest"
],
"env": {
"AWS_PROFILE": "sagemaker-wa-mcp-readonly-profile",
"AWS_REGION": "us-east-1",
"FASTMCP_LOG_LEVEL": "INFO"
},
"autoApprove": [
"validate_sagemaker_resource",
"validate_all_endpoints",
"list_sagemaker_resources",
"get_pillar_details"
]
}
}
}For Windows:
{
"mcpServers": {
"awslabs.sagemaker-wa-mcp-server": {
"command": "uvx",
"args": [
"--from",
"awslabs.sagemaker-wa-mcp-server@latest",
"awslabs.sagemaker-wa-mcp-server.exe"
],
"env": {
"AWS_PROFILE": "sagemaker-wa-mcp-readonly-profile",
"AWS_REGION": "us-east-1",
"FASTMCP_LOG_LEVEL": "INFO"
},
"autoApprove": [
"validate_sagemaker_resource",
"validate_all_endpoints",
"list_sagemaker_resources",
"get_pillar_details"
]
}
}
}In accordance with security best practices, we recommend the following:
Create dedicated IAM roles to be used by the SageMaker Well-Architected MCP Server with the principle of "least privilege."
Use read-only roles since the server only performs describe and list operations.
Implement resource tagging to limit actions to specific resources.
Enable AWS CloudTrail to audit all API calls made by the server.
Regularly review the permissions granted to the server's IAM role.
Use IAM Access Analyzer to identify unused permissions that can be removed.
IMPORTANT: Do not pass secrets or sensitive information via allowed input mechanisms:
Do not include secrets or credentials in tool parameters.
Do not pass sensitive information directly in the prompt to the model.
Avoid using MCP tools for creating secrets, as this would require providing the secret data to the model.
Instead of passing secrets through MCP:
Use AWS Secrets Manager or Parameter Store to store sensitive information.
Configure proper IAM roles for service accounts.
Use IAM roles for service accounts (IRSA) for AWS service access.
Important: This MCP server is intended for STDIO mode only as a local server using a single user's credentials. The server runs with the same permissions as the user who started it and has complete access to the file system.
Read-Only Operations: The server does not write to the file system or modify any AWS resources
Host Credentials: The server uses the host's AWS credentials configuration
Do Not Modify for Network Use: This server is designed for local STDIO use only; network operation introduces additional security risks
Resource Naming: Use descriptive names for SageMaker resources.
Error Handling: Check for errors in tool responses and handle them appropriately.
Prioritize Findings: Address HIGH severity findings first, then MEDIUM, then LOW.
Regular Audits: Run validations periodically to catch configuration drift.
Monitoring: Monitor resource status regularly.
Security: Follow AWS security best practices for SageMaker resources.
Permission Errors: Verify that your AWS credentials have the necessary read-only SageMaker permissions.
Resource Not Found: Verify the resource name and region are correct.
SageMaker API Errors: Verify that the SageMaker resources exist and are accessible.
Network Issues: Check that the environment has network access to AWS APIs.
Client Errors: Verify that the MCP client is configured correctly.
Log Level: Increase the log level to DEBUG for more detailed logs.
For service-specific issues, consult the relevant documentation:
Current MCP server version: 0.1.0
Get detailed information about a specific Well-Architected pillar and its checks.
Returns the pillar description and all validation checks that are performed
for the specified pillar.
Args:
ctx: MCP context
pillar: Pillar name
Returns:
PillarInfoResponse with pillar details and checks
| Name | Required | Description | Default |
|---|---|---|---|
| pillar | Yes | Pillar name: security, reliability, performance, cost, operational_excellence, or sustainability. |
| Name | Required | Description |
|---|---|---|
| name | Yes | Pillar name |
| checks | Yes | List of checks for this pillar |
| content | Yes | Response content |
| isError | No | Whether this is an error response |
| description | Yes | Pillar description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral-disclosure burden. It clearly implies a read operation and states the return contents, which is useful, but it does not mention permissions, invalid-pillar behavior, or any other side effects. Core behavior is adequately described, but with 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 opening sentence is clear and front-loaded, but the Returns line largely repeats the first sentence, and the Args/Returns blocks duplicate what the schema and output schema already provide. The description is compact but contains redundant docstring sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with an output schema available, the description is largely complete: it names the target pillar, the returned data, and the checks included. It lacks usage guidance around siblings and edge-case behavior, but these are minor for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the pillar parameter already has a descriptive enum-like list of valid values. The description only repeats 'pillar: Pillar name' and adds no meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific operation (get) and resource (a Well-Architected pillar), and explicitly describes what is returned: the pillar description and all validation checks. This helps an agent distinguish it from sibling tools, which focus on validating SageMaker resources rather than fetching pillar details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but gives no guidance on when to use it versus the sibling validation tools or list_sagemaker_resources. No alternatives, exclusions, or contextual triggers are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List SageMaker resources available for validation.
Returns endpoints, training jobs, notebook instances, and models
in the specified region.
Args:
ctx: MCP context
region_name: AWS region name (default: us-east-1)
profile_name: AWS profile name (optional)
Returns:
ListResourcesResponse with resource lists
| Name | Required | Description | Default |
|---|---|---|---|
| region_name | No | AWS region name. Default is us-east-1. | us-east-1 |
| profile_name | No | AWS profile name. If not provided, uses the default profile. |
| Name | Required | Description |
|---|---|---|
| models | No | List of models |
| content | Yes | Response content |
| isError | No | Whether this is an error response |
| endpoints | No | List of endpoints |
| training_jobs | No | List of training jobs |
| notebook_instances | No | List of notebook instances |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It discloses the read-only nature via 'List', the resource categories, and region scoping. However, it does not cover pagination, credential/auth requirements, resource status filtering, or error 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 summary sentence is front-loaded and clearly communicates purpose. The docstring-style Args/Returns sections are scannable and compact, though the Args section repeats 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 optional-parameter list call with an output schema, the essential invocation information is present. But it omits when-to-use guidance and notes on auth/credential assumptions, making it adequate rather than 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%, so the schema already documents both region_name and profile_name. The description adds no substantive semantics beyond re-stating defaults and optionality, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List'), resource ('SageMaker resources'), and scope ('available for validation', 'in the specified region'), and enumerates returned resource types. It clearly distinguishes from sibling 'validate_*' tools by its listing focus, though it doesn't name the alternatives explicitly.
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?
'available for validation' hints at a pre-validation enumeration step, but the description gives no explicit conditions for when to use this tool vs validate_sagemaker_resource, validate_all_endpoints, or validate_all_resources. There are no exclusions or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate all SageMaker endpoints in a region against Well-Architected pillars.
Scans all endpoints in the specified region and returns aggregated findings
across all six Well-Architected pillars.
Args:
ctx: MCP context
region_name: AWS region name (default: us-east-1)
profile_name: AWS profile name (optional)
Returns:
ValidateAllResponse with aggregated findings
| Name | Required | Description | Default |
|---|---|---|---|
| region_name | No | AWS region name. Default is us-east-1. | us-east-1 |
| profile_name | No | AWS profile name. If not provided, uses the default profile. |
| Name | Required | Description |
|---|---|---|
| content | Yes | Response content |
| isError | No | Whether this is an error response |
| summary | Yes | Aggregated findings summary by pillar |
| findings | Yes | List of all findings |
| total_findings | Yes | Total number of findings |
| resources_validated | Yes | List of validated resource names |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the core behavior: scanning all endpoints and returning aggregated findings across six pillars, implying a read-only operation. Since no annotations are provided, the description carries the behavioral burden, but it does not mention AWS permission needs, potential API call volume, pagination, or failure behavior. This is adequate but not rich.
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 front-loaded with a clear purpose and uses a structured docstring format. However, the Args and Returns sections largely duplicate information already available in the input schema and output schema, making 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?
The description covers the essential operation, scope, and return shape, and the output schema exists to define the response. It is incomplete in one important way: it does not clarify how this tool relates to validate_all_resources or when to choose one over the other, which is a notable gap given the sibling tools.
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%: both region_name and profile_name already have descriptions and defaults in the input schema. The description's Args section repeats this information without adding semantic depth beyond what the schema provides.
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 ('Validate'), a specific resource ('all SageMaker endpoints'), a scope ('in a region'), and a framework ('Well-Architected pillars'). It clearly differentiates from single-resource validation tools by emphasizing 'all endpoints' and aggregated findings.
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 usage context is implied: it is for validating every endpoint in a region rather than a single resource. However, the description does not explicitly distinguish this from the sibling tool validate_all_resources, nor does it state when an agent should prefer one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate all SageMaker resources in a region against Well-Architected pillars.
Scans all endpoints, training jobs, notebook instances, and models in the
specified region. Returns an on-screen summary and generates a single
comprehensive HTML report (wa-report.html) with all findings.
Args:
ctx: MCP context
region_name: AWS region name (default: us-east-1)
profile_name: AWS profile name (optional)
Returns:
ValidateAllResponse with aggregated findings and path to HTML report
| Name | Required | Description | Default |
|---|---|---|---|
| region_name | No | AWS region name. Default is us-east-1. | us-east-1 |
| profile_name | No | AWS profile name. If not provided, uses the default profile. |
| Name | Required | Description |
|---|---|---|
| content | Yes | Response content |
| isError | No | Whether this is an error response |
| summary | Yes | Aggregated findings summary by pillar |
| findings | Yes | List of all findings |
| total_findings | Yes | Total number of findings |
| resources_validated | Yes | List of validated resource names |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does reasonably well: it names the scan scope, states the on-screen summary behavior, and discloses the file-generation side effect (wa-report.html). It does not cover credential requirements, runtime duration, or failure modes, but the most decision-relevant behaviors are disclosed.
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 one-sentence purpose is front-loaded, followed by a compact paragraph on scope and outputs. The Args and Returns sections are slightly redundant with the input and output schemas, but the docstring format is standard and there is no padding 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 region-wide multi-resource scan, the description covers the essentials: what is scanned, what artifacts are produced (on-screen summary, HTML report), and what the response contains. Since an output schema exists for ValidateAllResponse, return-value detail is already structured. Missing are performance/cost expectations and sibling routing, but the description is complete enough for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters fully, including defaults and the profile fallback behavior. The Args section merely restates the schema descriptions and adds no new semantic detail. Baseline 3 applies because the structured data carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb (validate), resource (all SageMaker resources in a region), and standard (Well-Architected pillars), then enumerates the scanned types: endpoints, training jobs, notebook instances, and models. This scope clearly differentiates it from siblings validate_sagemaker_resource (singular resource) and validate_all_endpoints (endpoints only).
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 context is implied by the scope statement — an agent can infer this is the broadest validation sweep — but the description never explicitly says when to prefer it over validate_sagemaker_resource or validate_all_endpoints. There is no when-not-to-use guidance or mention of sibling alternatives. The resource enumeration gives partial routing signal, but the choice rule is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a SageMaker resource against all Well-Architected Framework pillars.
Checks security, reliability, performance efficiency, cost optimization,
operational excellence, and sustainability best practices for the specified resource.
## Supported Resource Types
- **endpoint**: SageMaker real-time inference endpoints
- **training_job**: SageMaker training jobs
- **notebook_instance**: SageMaker notebook instances
- **model**: SageMaker models
## Checks Performed
- **Security**: KMS encryption, VPC isolation, network isolation, inter-container encryption
- **Reliability**: Multi-instance endpoints, training timeouts, checkpointing, retry strategies
- **Performance**: Instance generation, data capture, data distribution, instance sizing
- **Cost**: Cost tags, spot training, serverless inference, lifecycle configs
- **Operational Excellence**: Operational tags, auto-scaling, experiment tracking
- **Sustainability**: Graviton instances, spot utilization, right-sizing
## Fallback Options
- If this tool fails, use AWS CLI: `aws sagemaker describe-endpoint --endpoint-name <name>`
- Or use the AWS SageMaker Console to review resource configurations
Args:
ctx: MCP context
resource_type: Type of SageMaker resource
resource_name: Name of the resource to validate
region_name: AWS region name (default: us-east-1)
profile_name: AWS profile name (optional)
Returns:
ValidateResourceResponse with findings and summary
| Name | Required | Description | Default |
|---|---|---|---|
| region_name | No | AWS region name. Default is us-east-1. | us-east-1 |
| profile_name | No | AWS profile name. If not provided, uses the default profile. | |
| resource_name | Yes | Name of the SageMaker resource to validate. | |
| resource_type | Yes | Type of SageMaker resource: endpoint, training_job, notebook_instance, or model. |
| Name | Required | Description |
|---|---|---|
| content | Yes | Response content |
| isError | No | Whether this is an error response |
| summary | Yes | Findings summary by pillar |
| findings | Yes | List of findings |
| resource | Yes | Name of the validated resource |
| resource_type | Yes | Type of the resource |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and mostly meets it: it enumerates all six pillar checks, concrete examples per pillar, and a fallback path. It does not explicitly state side-effect freedom or IAM requirements, but 'validate' and 'checks' strongly imply a read-only assessment.
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 longer than average but well-structured with headings for supported types, checks, fallback, arguments, and returns. The front-loaded summary is effective, and each section adds operational value rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex validation tool with no annotations and an output schema, the description covers supported inputs, the exact pillar checks, fallbacks, and the response shape. It omits permission requirements and error behavior, but the provided context is sufficient for selecting and invoking the tool correctly in most 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 description coverage is 100%, so the schema already documents all four parameters. The description's Args section largely repeats those definitions and even mentions ctx, which is not part of the input schema; the only added value is the expanded resource-type list and example checks, which are not strictly 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 opening sentence states a specific action and object: 'Validate a SageMaker resource against all Well-Architected Framework pillars.' The Supported Resource Types section and singular 'resource_name' make the single-resource scope clear, distinguishing it from siblings like validate_all_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?
The description gives clear context by listing supported resource types and fallback CLI/console options, but it never explicitly says when to prefer this tool over the sibling validation tools. The singular-resource scope is implied rather than stated as an alternative, so an agent must infer the routing decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_pillar_detailslist_sagemaker_resourcesvalidate_all_endpointsvalidate_all_resourcesvalidate_sagemaker_resourceScored across 5 tools
Each tool has a clear purpose: validate a single resource, validate all endpoints, validate all resources, list resources, and get pillar details. The only potential confusion is between validate_all_endpoints and validate_all_resources, since the former is a subset of the latter, but the descriptions clearly distinguish their scopes.
Tool names follow a consistent verb_noun pattern: validate_*, list_*, and get_*. All names are snake_case and clearly indicate the action being performed, with no mixed conventions or vague verbs.
Five tools is well-scoped for a SageMaker Well-Architected validation server. Each tool serves a distinct and necessary function, covering single-resource validation, bulk validation, listing, and reference information without unnecessary bloat.
The tool set covers the full validation workflow: discover resources, validate an individual resource, validate all resources, validate all endpoints specifically, and understand the pillars being checked. There are no obvious dead ends or missing operations for the stated domain.
Statically audits MCP tool surfaces for token cost, schema quality, and design issues.
Discover Frontier inference capabilities and read sanitized usage through read-only tools.
Lowers your AWS bill by helping you clean up and optimize your setup
Read-only, deterministic AI triage and readiness tools implementing Sophon's published rubrics.
