CoreStack MCP Tools - Complete Documentation
Introduction
This document provides comprehensive documentation for all MCP (Model Context Protocol) tools available in the CoreStack AI Agent system.
Well-Architected Framework (WAF) Assessment Tools
Assessment Definition Tools
assessment_definition_list_and_retrieval
Fetch assessment definitions for the selected tenant.
| Parameter | Type | Description | Required |
|---|---|---|---|
| batch_size | int | Number of definitions per page (default 10) | Optional |
| batch_offset | int | Offset for pagination (default 0) | Optional |
| Total | int | Total number of definitions (default 0) | Optional |
| sort_column | str | Column to sort by (default ‘UpdatedOn’) | Optional |
| sort_ascending | bool | Sort ascending if True (default False) | Optional |
| query_type | str | Filter by query type (default ‘AssessmentQueryAssessmentName’) | Optional |
| query_name | str | Filter by query name (default ’’) | Optional |
Returns: Dict containing details of assessment definitions matching criteria.
Sample Questions:
- “Get all assessment definitions for the current tenant”
- “Show me the latest 20 assessment definitions sorted by update date”
- “Find assessment definitions with name containing ‘security’”
Assessment Run Tools
assessment_run_list_and_retrieval
Fetch and list details of assessment runs for specified assessment definitions.
| Parameter | Type | Description | Required |
|---|---|---|---|
| assessment_definition_ids | list[str] | List of assessment definition sysIds to fetch runs for. | Mandatory |
Returns: Dict containing list of assessment run details for the specified assessment definitions.
Sample Questions:
- “Get all assessment runs for definition ID ‘def-123’”
- “Show me assessment runs for these definition IDs: [‘def-123’, ‘def-456’]”
assessment_run_history_list_and_retrieval
Fetch the details of history_ids of specified assessment runs by their IDs.
| Parameter | Type | Description | Required |
|---|---|---|---|
| assessment_run_ids | list[dict] | List of assessment run IDs with optional lastUpdate and table fields. | Mandatory |
Returns: Dict containing a list of assessment run history objects for the specified IDs.
Sample Questions:
- “Get history for assessment run ID ‘run-123’”
get_violations_by_policy_job
Get a list of RecordIdentity for resources that have violated the given policy job.
| Parameter | Type | Description | Required |
|---|---|---|---|
| assessment_run_history_id | str | The ID of the assessment run history. | Mandatory |
| policy_job_id | str | The ID of the policy job. | Mandatory |
Returns: List of RecordIdentity objects for the violated resources.
Sample Questions:
- “Show me all resource violations for policy job ‘job-123’ in run history ‘hist-456’”
- “What resources violated this policy in the latest assessment?”
generate_assessment_report
Schedule the generation of a report for an assessment run.
| Parameter | Type | Description | Required |
|---|---|---|---|
| assessment_run_sys_id | str | The ID of the assessment run. | Mandatory |
| framework_id | str | The ID of the framework. | Mandatory |
| last_update | str | The last updated timestamp. | Optional |
| Table | str | The context of the tracked item. | Optional |
| export_format | str | The export format (default is “PDF”). | Optional |
| filter_model | dict | The filter model for the report. | Optional |
Returns: Response containing the sysId, last_update, and table of the report.
Sample Questions:
- “Generate a PDF report for assessment run ‘run-123’ using framework ‘aws-waf’”
- “Create an Excel report for the latest security assessment”
assessment_run_question_list_and_retrieval
Get all the details of questions for the selected assessment runs history IDs.
| Parameter | Type | Description | Required |
|---|---|---|---|
| assessment_run_history_ids | list[dict] | Assessment run history ID objects with optional lastUpdate and table fields. | Mandatory |
Returns: Dict containing a list of Question objects for the selected assessment runs.
Sample Questions:
- “Get all questions from assessment run history ‘hist-123’”
- “Show me the questions answered in the latest WAF assessment”
get_pillar_wise_scores
Calculate Well-Architected Framework scores for each pillar in a given assessment run.
| Parameter | Type | Description | Required |
|---|---|---|---|
| assessment_run_id | str | The system ID of the assessment run to generate scores for. | Mandatory |
Returns: Dict of pillar score results with pillar_id as key and calculated score as value.
Sample Questions:
- “Calculate pillar scores for assessment run ‘run-123’”
- “What are the security and reliability scores for the latest assessment?”
answer_question_or_best_practice
Answer a question or best practice with attachments, comments, and state management.
| Parameter | Type | Description | Required |
|---|---|---|---|
| assessment_run_id | str | The ID of the assessment run. | Mandatory |
| framework_id | str | The ID of the framework. | Mandatory |
| pillar_id | str | The ID of the pillar. | Mandatory |
| question_id | str | The ID of the question. | Mandatory |
| best_practice_id | str | The ID of the best practice. | Mandatory |
| created_by | str | The user who created the answer. | Mandatory |
| Owner | str | The owner of the answer. | Mandatory |
| assigned_to | list[str] | List of users assigned to the answer. | Optional |
| attachment_ids | list[str] | List of attachment IDs | Optional |
| comment_id | str | The ID of the comment. | Optional |
| comment | str | The comment text. | Optional |
| recommendation | str | The recommendation text. | Optional |
| sync_failure_reason | str | The reason for sync failure. | Optional |
| Status | str | The status of the answer (default “Open”). | Optional |
| created_on | str | The creation timestamp (ISO format). | Optional |
Returns: Response containing the assessment run details and answers list.
Sample Questions:
- “Answer question ‘q1’ in assessment ‘run-123’ with status ‘Verified’”
- “Add a comment to best practice ‘bp1’ saying it’s implemented”
Framework Tools
framework_list_and_retrieval
Retrieve the frameworks and details for the selected tenant.
| Parameter | Type | Description | Required |
|---|---|---|---|
| None | - | - | - |
Returns: Dict containing a list of framework objects including pillars and questions.
Sample Questions:
- “Show me all available frameworks”
- “List the AWS Well-Architected Framework details”
question_batch_retrieval
Retrieve questions for given question IDs.
| Parameter | Type | Description | Required |
|---|---|---|---|
| question_ids | list[dict] | List of question identifiers with optional lastUpdate and table fields. | Mandatory |
Returns: Dict containing a list of question objects including details and last update timestamps.
Sample Questions:
* “Get details for question IDs [{‘sysId’: ‘q1’}, {‘sysId’: ‘q2’}, {‘sysId’: ‘q3’}]” best_practice_batch_retrieval
Fetch best practices for given system IDs.
| Parameter | Type | Description | Required |
|---|---|---|---|
| best_practice_ids | list[dict] | List of best practice identifiers with optional lastUpdate and table fields. | Mandatory |
Returns: Dict containing a list of best practice objects.
Sample Questions:
“Get best practices for IDs [{‘sysId’: ‘bp1’}, {‘sysId’: ‘bp2’}, {‘sysId’: ‘bp3’}]”Policy Tools
get_policy_descriptions
Retrieve policy descriptions for given policy URIs.
| Parameter | Type | Description | Required |
|---|---|---|---|
| policy_uris | list[str] | List of policy URIs to retrieve descriptions for. | Mandatory |
Returns: Policy descriptions mapped by URI or error information if the operation fails.
Sample Questions:
- “Get descriptions for policy URIs [‘uri1’, ‘uri2’]”
get_policy_job_batch
Retrieve policy job execution details for given policy job IDs.
| Parameter | Type | Description | Required |
|---|---|---|---|
| policy_job_ids | list[str] | List of policy job IDs to retrieve execution details for. | Mandatory |
Returns: Policy job execution details including output data and cloud account information.
Sample Questions:
- “Get execution details for policy jobs [‘job1’, ‘job2’]”
get_policy_job_details
Retrieve detailed execution information for a single policy job.
| Parameter | Type | Description | Required |
|---|---|---|---|
| tenant_id | str | The tenant ID. | Mandatory |
| policy_job_id | str | The policy job ID to retrieve details for. | Mandatory |
Returns: Detailed policy job execution information.
Sample Questions:
- “Get detailed execution info for policy job ‘job-123’”
- “Show me the violation details for the security policy job”
Workload Tools
Workload Definition Tools
workload_definition_list_and_retrieval
Get a list of workload definitions for the selected tenant.
| Parameter | Type | Description | Required |
|---|---|---|---|
| batch_size | int | Number of workloads per page (default 10). | Optional |
| batch_offset | int | Offset for pagination (default 0). | Optional |
| total | int | Total number of workloads (default 0). | Optional |
| sort_column | str | Column to sort by (default ‘Name’). | Optional |
| sort_ascending | bool | Sort ascending if True (default True). | Optional |
| filter_query | dict | Additional filters to apply to the workload query. | Optional |
Returns: Dict containing workload definition objects.
Sample Questions:
- “Show me all workload definitions”
- “Get the first 20 workloads sorted by name”
- “Find workloads with ‘production’ in the name”
create_workload_definition
Create a workload definition for the selected tenant.
| Parameter | Type | Description | Required |
|---|---|---|---|
| name | str | The name of the workload definition. | Mandatory |
| description | str | Description of the workload definition. | Mandatory |
| workload_type | str | The type of the workload definition. | Mandatory |
| attachments | list[str] | List of attachment ids associated with the workload definition. | Optional |
| owner | str | The id of the owner of the workload definition. | Optional |
| is_active | bool | Whether the workload definition is active (default True). | Optional |
| tiers | list[Tier] | List of tiers composing the workload definition. | Optional |
| tags | list[Tag] | List of tags associated with the workload definition. | Optional |
Returns: Dict containing workload version details including sysId, timestamps, and definition info.
Sample Questions:
- “Create a new workload definition called ‘Web Application Stack’”
- “Set up a workload for our microservices architecture”
Workload Version Tools
get_workload_definition_version_details
Get details on a specific Workload Definition Version by id.
| Parameter | Type | Description | Required |
|---|---|---|---|
| version_id | str | The ID of the Workload Definition Version to retrieve. | Mandatory |
Returns: Dict containing Workload Definition Version details.
Sample Questions:
- “Get details for workload version ‘ver-123’”
- “Show me details for the release version of the web application workload”
Workload Query Tools
workload_query_list_and_retrieval
Execute a query against the ServiceResourceInventory collection given a WorkloadTierConfiguration.
| Parameter | Type | Description | Required |
|---|---|---|---|
| batch_size | int | Number of workloads per page (default 10). | Optional |
| batch_offset | int | Offset for pagination (default 0). | Optional |
| total | int | Total number of workloads (default 0). | Optional |
| sort_column | str | Column to sort by (default ‘CloudAccountName’). | Optional |
| sort_ascending | bool | Sort ascending if True (default True). | Optional |
| filters | dict | Additional filters including name, description, owner, cloud_account_id, and resource_filter. | Optional |
Returns: Resource objects for resources matching the query.
Sample Questions:
- “Query all resources in the production workload”
- “Find EC2 instances in workload tier ‘web-servers’”
- “Show me all resources owned by ‘[email protected]’”
Resource Tools
get_resource_batch
Retrieve detailed resource information in batches for given resource IDs.
| Parameter | Type | Description | Required |
|---|---|---|---|
| resource_ids | list[str] | List of resource IDs to retrieve details for. | Mandatory |
| batch_size | int | Number of resources to fetch per batch (default 250). | Optional |
Returns: Resource details for the specified IDs.
Sample Questions:
- “Get details for resource IDs [‘res-123’, ‘res-456’]”
- “Show me information about all EC2 instances in the batch”
get_workload_resource_filters
Retrieve resource filter data for given service account IDs.
| Parameter | Type | Description | Required |
|---|---|---|---|
| service_account_ids | list[str] | List of service account IDs to get resource filters for. | Mandatory |
Returns: Resource filter data including categories, types, and resource names.
Sample Questions:
- “Get resource filters for service account ‘acc-123’”
- “Show me available filter options for AWS accounts”
Agent Management Tools
Agent Type Tools
agent_type_retrieval
Get agent types available to the given tenant.
| Parameter | Type | Description | Required |
|---|---|---|---|
| None | - | - | - |
Returns: Dict containing the agent types available to the given tenant.
Sample Questions:
- “Show me all available agent types”
- “What AI agents can I use for assessments?”
Chat Management Tools
chat_list_and_retrieval
Get chat details based on the provided filtering criteria.
| Parameter | Type | Description | Required |
|---|---|---|---|
| filter_agent_id | str | The ID of the agent to filter the chats by. | Mandatory |
| batch_size | int | The number of chats to retrieve per batch (default 10). | Optional |
| batch_offset | int | The offset for pagination (default 0). | Optional |
| total | int | The total number of chats to retrieve (default 0). | Optional |
| sort_column | str | The column to sort the results by (default “Name”). | Optional |
| sort_ascending | bool | Whether to sort the results in ascending order (default True). | Optional |
| filter_name | str | The name of the chat to filter by. | Optional |
Returns: Dict containing the chat details for the given filter criteria.
Sample Questions:
- “Show me all chats for agent ‘assessment-agent’”
- “Find chats with ‘security’ in the name”
conversation_list_and_retrieval
Fetch the details of conversations for the specified chat based on the given filters.
| Parameter | Type | Description | Required |
|---|---|---|---|
| filter_chat_id | str | The ID of the chat to filter by. | Mandatory |
| batch_size | int | The number of conversations to retrieve per batch (default 10). | Optional |
| batch_offset | int | The offset for pagination (default 0). | Optional |
| total | int | The total number of conversations to retrieve (default 0). | Optional |
| sort_column | str | The column to sort the results by (default “CreatedAt”). | Optional |
| sort_ascending | bool | Whether to sort the results in ascending order (default True). | Optional |
Returns: Dictionary containing the retrieved conversations and their metadata.
Sample Questions:
- “Get all conversations from chat ‘chat-123’”
- “Show me the latest 10 messages from this chat session”
submit_new_query
Submit a new query for the specified chat and retrieve the agent’s response.
| Parameter | Type | Description | Required |
|---|---|---|---|
| chat_id | str | The ID of the chat session. | Mandatory |
| agent_id | str | The ID of the agent to use for the request. | Mandatory |
| query | str | The user’s query to send to the agent. | Mandatory |
Returns: Dictionary containing the conversation id, agent response, and other metadata.
Sample Questions:
- “Ask the assessment agent about security best practices”
- “Submit query ‘How do I improve my reliability score?’ to chat ‘chat-123’”
Prompt Management Tools
system_prompt_list_and_retrieval
Retrieve the details of saved prompts matching the filtering criteria.
| Parameter | Type | Description | Required |
|---|---|---|---|
| filters_agent_ids | list[str] | A list of agent IDs to filter the prompts by. | Mandatory |
| filters_prompt_type | str | The type of prompts to filter by (default “default”). | Optional |
| filters_prompt | str | The name of the prompt to filter by. | Optional |
| tags | list[Tag] | A list of tags to filter by with structure {“key”: key, “value”: value}. | Optional |
| batch_size | int | The number of prompts to retrieve per batch (default 10). | Optional |
| batch_offset | int | The offset for pagination (default 0). | Optional |
| total | int | The total number of prompts to retrieve (default 0). | Optional |
| sort_column | str | The column to sort the results by (default “CreatedAt”). | Optional |
| sort_ascending | bool | Whether to sort the results in ascending order (default True). | Optional |
Returns: Dictionary containing the retrieved system prompts and their metadata.
Sample Questions:
- “Get all prompts for agent ‘assessment-agent’”
- “Show me security-related prompts with tag ‘category:security’”
Authentication Tools
Connection Management
connect_to_corestack
Connect to CoreStack by walking the user through the authentication steps.
| Parameter | Type | Description | Required |
|---|---|---|---|
| None | - | Uses HTTP headers for authentication. | - |
Returns: Dictionary containing connection status details.
Sample Questions:
- “Connect me to CoreStack” - “Establish authentication with the CoreStack platform”
switch_tenant
Switch the selected tenant ID for subsequent requests.
| Parameter | Type | Description | Required |
|---|---|---|---|
| None | - | - | - |
Returns: Dict containing status information.
Sample Questions:
- “Change to a different tenant”
switch_master_account
Switch the master account ID for subsequent requests.
| Parameter | Type | Description | Required |
|---|---|---|---|
| None | - | - | - |
Returns: Dict containing status information.
Sample Questions:
- “Change to a different master account”
Usage Notes
Authentication Requirements
All tools (except authentication tools) require proper authentication via HTTP headers:
- X-API-ACCESS-KEY: Your CoreStack access key
- X-API-SECRET-KEY: Your CoreStack secret key
- X-API-URL: The CoreStack API base URL
- X-ACCOUNT-MASTER-ID: Master account ID (optional)
- X-TENANT-ID: Tenant ID (optional)
Updated about 3 hours ago