View a markdown version of this page

Start a tool description recommendation - Amazon Bedrock AgentCore
Code samplesRequest parametersTool description input modesResponseRecommendation resultErrors

Start a tool description recommendation

Start a recommendation to generate optimized tool descriptions for your agent. The service analyzes agent traces to identify tool selection confusion and produces sharpened descriptions that reduce ambiguity when the agent chooses between tools.

Note

Recommendations are generated by LLMs. Review and test before applying them.

Code samples

Example
AgentCore CLI

Inline tool descriptions with CloudWatch traces:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID, initiate_return:Initiate a return for an order" \
  --lookback 7

Inline tool descriptions with a spans file:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID, initiate_return:Initiate a return for an order" \
  --spans-file agent-traces.json

Inline tool descriptions with specific session IDs:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID, initiate_return:Initiate a return for an order" \
  --session-id 12345678-1234-1234-1234-123456789012

Configuration bundle with CloudWatch traces:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:$.configuration.tools.lookup_order.description" \
  --tool-desc-json-path "initiate_return:$.configuration.tools.initiate_return.description" \
  --lookback 7

Configuration bundle with a spans file:

agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:$.configuration.tools.lookup_order.description" \
  --tool-desc-json-path "initiate_return:$.configuration.tools.initiate_return.description" \
  --spans-file agent-traces.json
AWS SDK (boto3)

Inline tool descriptions with CloudWatch traces:

import boto3
import json
import uuid
from datetime import datetime, timedelta, timezone

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

now = datetime.now(timezone.utc)

response = client.start_recommendation(
    name="my-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

recommendation_id = response["recommendationId"]
print(f"Started recommendation: {recommendation_id}")
print(f"Status: {response['status']}")

Inline tool descriptions with inline spans:

with open("agent-traces.json") as f:
    spans = json.load(f)

response = client.start_recommendation(
    name="my-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Configuration bundle with CloudWatch traces:

response = client.start_recommendation(
    name="my-bundle-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Configuration bundle with inline spans:

response = client.start_recommendation(
    name="my-bundle-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Request parameters

Parameter Type Required Description

name

String

Yes

A name for the recommendation. Maximum 48 characters. Pattern: [a-zA-Z][a-zA-Z0-9_-]{0,47}.

type

String

Yes

Must be TOOL_DESCRIPTION_RECOMMENDATION.

recommendationConfig

Object

Yes

Contains toolDescriptionRecommendationConfig with the configuration for the recommendation.

description

String

No

Optional description. Maximum 4096 characters.

clientToken

String

No

Idempotency token. If you retry a request with the same client token, the service returns the existing recommendation instead of creating a new one.

toolDescriptionRecommendationConfig fields

Field Type Required Description

toolDescription

Union

Yes

The current tool descriptions to optimize. Provide either toolDescriptionText (inline list of tool name and description pairs) or configurationBundle (bundle reference with JSON paths to each tool description).

agentTraces

Union

Yes

Trace source for analysis. See Trace sources for recommendations.
Note

Tool description recommendations do not require an evaluationConfig. Unlike system prompt recommendations, which use an evaluator as the optimization signal, tool description recommendations analyze tool selection patterns directly from the agent traces to identify ambiguity between tools and generate sharpened descriptions.

Tool description input modes

Mode CLI flags API field

Inline text

--tools "name:description, name:description"

toolDescription.toolDescriptionText.tools. List of objects with toolName and toolDescription

Configuration bundle

--bundle-name <bundle-name> + --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath" (repeat for each tool)

toolDescription.configurationBundle with bundleArn, versionId, and tools list containing toolName and toolDescriptionJsonPath

When using a configuration bundle, the result includes a new bundle version with the optimized tool descriptions applied.

Response

Field Type Description

recommendationId

String

Unique identifier for the recommendation.

recommendationArn

String

ARN of the recommendation.

name

String

The name you specified.

type

String

TOOL_DESCRIPTION_RECOMMENDATION.

status

String

Initial status: PENDING or IN_PROGRESS.

createdAt

Timestamp

When the recommendation was created.

updatedAt

Timestamp

When the recommendation was last updated.

Recommendation result

When the recommendation reaches COMPLETED status (retrieved via Get a recommendation), the result contains:

Field Type Description

tools

List

Per-tool results. Each entry contains toolName and recommendedToolDescription.

configurationBundle

Object

Present when the input was a configuration bundle. Contains bundleArn and versionId pointing to a new bundle version with the optimized descriptions applied.

errorCode

String

Present if the recommendation failed. Error code describing the failure.

errorMessage

String

Present if the recommendation failed. Human-readable error description.

Errors

Error HTTP status Description

ValidationException

400

Invalid request parameters. Check field constraints and required fields.

AccessDeniedException

403

Insufficient permissions. Verify IAM policies.

ConflictException

409

A recommendation with the same client token already exists with different parameters.

ServiceQuotaExceededException

402

You have exceeded the maximum number of concurrent recommendations.

ThrottlingException

429

Request rate exceeded. Retry with exponential backoff.

InternalServerException

500

Service-side error. Retry the request.