Skip to content
CLI (Treasure Code)
/
/
Web Search Tool
Last updated

Web Search Tool Setup Guide

This guide explains how to add web search capabilities to AI Agent Foundry agents.

Prerequisites

  • ✅ Experience creating and managing agents in AI Agent Foundry
  • ✅ TDX CLI installed and authenticated
Limitation

Web Search Tool is not visible in the console UI. Configuration is only possible via TDX CLI or Treasure Studio.

Setup Flow

1. Create Web Search Tool instance (API)
   ↓
2. Add tool to agent.yml (pull → edit → push)
   ↓
3. Test functionality

Step 1: Create Web Search Tool Instance

Get Project ID

# List projects with IDs
tdx llm project list --format json 2>&1 | tail -n +2 | jq -r '.[] | {id, name}'

# Or store in variable
PROJECT_ID="<your-project-id>"

Create Web Search Tool

cat > web_search_tool.json <<EOF
{
  "data": {
    "type": "webSearchTools",
    "attributes": {
      "name": "my_web_search_tool",
      "projectId": "$PROJECT_ID",
      "modelType": "gpt-5-mini",
      "systemPrompt": "You are a focused web search assistant. Answer only with the information requested.",
      "searchContextSize": "medium",
      "filters": {
        "allowed_domains": [
          "example.com",
          "openai.com"
        ]
      }
    }
  }
}
EOF

tdx api -X POST --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f web_search_tool.json \
  /api/web_search_tools

Save the data.id from the response for later direct API calls (for example, GET/PATCH) and verification. The agent.yml example in this guide refers to the tool by name.

Step 2: Add to agent.yml

Pull Existing Agent

# Pull agent configuration
tdx agent pull "Project Name" -y

Edit agent.yml

Add to agents/Project Name/agent-name/agent.yml:

tools:
  - type: web_search
    target: '@ref(type: "web_search_tool", name: "my_web_search_tool")'
    target_function: SEARCH
    function_name: search_web
    function_description: Search the web for current information

Key points:

  • target name must match attributes.name from Step 1
  • function_description guides the LLM's tool selection decisions

Apply Changes

tdx agent push "agents/Project Name/" -y

Step 3: Test

tdx chat --agent "Project Name/agent-name" \
  --new "What is the latest news about Anthropic?"

Success if web search executes and returns current information.

Configuration Reference

Web Search Tool Settings

ParameterRequiredDefaultDescription
name✅-Tool name (referenced in @ref)
projectId✅-Project ID
modelType✅-gpt-5-mini
systemPrompt❌nullSystem prompt for web search
searchContextSize❌mediumlow / medium / high
userLocation❌nullLocation object for regional optimization
filters.allowed_domainsConditional[]Allowed domain list (max 20, no https://). If you include filters, you must include allowed_domains; an empty array ([]) is allowed.

userLocation Example

"userLocation": {
  "type": "approximate",
  "country": "JP",
  "city": "Minato",
  "region": "Tokyo",
  "timezone": "Asia/Tokyo"
}

agent.yml Tools Configuration

FieldRequiredDescription
type✅web_search (fixed)
target✅@ref(type: "web_search_tool", name: "...")
target_function✅SEARCH (fixed)
function_name✅Function name shown to LLM
function_description✅Function description shown to LLM

Cost Optimization

To reduce costs:

  1. modelType: Use gpt-5-mini
  2. searchContextSize: Use low or medium (high is expensive)
  3. allowed_domains: Restrict to trusted domains only
  4. systemPrompt: Include instructions for concise responses

Update example:

cat > update.json <<EOF
{
  "data": {
    "type": "webSearchTools",
    "attributes": {
      "modelType": "gpt-5-mini",
      "searchContextSize": "low"
    }
  }
}
EOF

tdx api -X PATCH --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f update.json \
  /api/web_search_tools/<TOOL_ID>

Troubleshooting

Web search not executing

Cause:

  • Web Search Tool feature not enabled for account
  • Web Search Tool instance doesn't exist

Solution:

# Verify Web Search Tool exists
tdx api --type llm /api/web_search_tools | jq '.data[] | {id, name, projectId}'

# Contact Support for feature enablement

allowed_domains settings not applied

Cause:

  • Including https:// in domain names
  • Adding subdomains individually

Solution:

  • Specify domain only: openai.com (not https://openai.com)
  • Subdomains are automatically allowed (no need to add separately)

Higher costs than expected

Cause:

  • Using searchContextSize: high

Solution:

  • See "Cost Optimization" section above

Content-Type error (HTTP 415)

Cause:

  • Missing Content-Type: application/vnd.api+json header in API call

Solution:

# Required: include the Content-Type header
tdx api -X POST --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f payload.json \
  /api/web_search_tools

API Reference

Web Search Tool Operations

List all:

tdx api --type llm /api/web_search_tools

Get details:

tdx api --type llm /api/web_search_tools/<TOOL_ID>

Update:

tdx api -X PATCH --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f update.json \
  /api/web_search_tools/<TOOL_ID>

Delete:

tdx api -X DELETE --type llm /api/web_search_tools/<TOOL_ID>

Verify Agent Tools

# Check tools attached to agent
tdx api --type llm /api/agents/<AGENT_ID> | jq '.data.attributes.tools'

Expected output:

[
  {
    "toolTargetId": "<WEB_SEARCH_TOOL_ID>",
    "targetFunction": "SEARCH",
    "functionName": "search_web",
    "functionDescription": "Search the web for current information",
    "toolTargetType": "WebSearchTool"
  }
]

FAQ

Q: How to add to new project/agent?

A: After creating project, create Web Search Tool with new project ID in Step 1. For agent creation, use API with explicit projectId:

cat > agent.json <<EOF
{
  "data": {
    "type": "agents",
    "attributes": {
      "name": "new-agent",
      "projectId": "$PROJECT_ID",
      "systemPrompt": "Your prompt here",
      "modelType": "claude-4.5-sonnet"
    }
  }
}
EOF

tdx api -X POST --type llm \
  -H "Content-Type: application/vnd.api+json" \
  -f agent.json \
  /api/agents

Q: Correct Claude model name format?

A: claude-4.5-sonnet (note hyphens and periods)

Q: Using multiple tools together?

A: Add multiple tool definitions under tools: in agent.yml:

tools:
  - type: knowledge_base
    target: '@ref(type: "knowledge_base", name: "product-catalog")'
    target_function: SEARCH
    function_name: search_products
    function_description: Search internal product catalog

  - type: web_search
    target: '@ref(type: "web_search_tool", name: "my_web_search_tool")'
    target_function: SEARCH
    function_name: search_web
    function_description: Search the web for current information

Document Version: v2.1 Last Updated: 2026-03-16

TD Skills

API Command Safety