# Start a tool description recommendation
<a name="recommendations-tool-description"></a>

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
<a name="start-tooldesc-rec-examples"></a>

**Example**  
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
```
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
<a name="start-tooldesc-rec-params"></a>


| 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
<a name="start-tooldesc-rec-config"></a>


| 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](optimization-recommendations.md#recommendations-trace-sources). | 

**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
<a name="start-tooldesc-rec-input-modes"></a>


| 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
<a name="start-tooldesc-rec-response"></a>


| 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
<a name="start-tooldesc-rec-result"></a>

When the recommendation reaches `COMPLETED` status (retrieved via [Get a recommendation](recommendations-get.md)), 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
<a name="start-tooldesc-rec-errors"></a>


| 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. |