Tool Design & Tool Choice Strategy

# BAD: descriptions overlap, Claude will guess.
tools = [
    {"name": "analyze_content",  "description": "Analyzes content."},
    {"name": "analyze_document", "description": "Analyzes a document."},
]

# GOOD: each description names what the OTHER tool is NOT for.
tools = [
    {
        "name": "analyze_content",
        "description": (
            "Analyzes a single piece of inline text or HTML passed as a string "
            "(blog post body, email draft, social copy). Use this when the caller "
            "has the content in-hand. DO NOT use for files on disk or document IDs, "
            "use analyze_document for those."
        ),
    },
    {
        "name": "analyze_document",
        "description": (
            "Analyzes a stored document referenced by document_id (PDF, Word, "
            "uploaded file). Use this when the caller has only an identifier or "
            "a file path. DO NOT use for raw inline text, use analyze_content."
        ),
    },
]

# STARTING POINT: both tools sound like generic analysis.
tools = [
    {"name": "analyze_content", "description": "Analyze content and return key points."},
    {"name": "analyze_document", "description": "Analyze a document and return key points."},
]

# TARGET DESIGN: split by function and input source.
tools = [
    {
        "name": "analyze_uploaded_document",
        "description": (
            "Extracts claims and entities from an uploaded PDF/DOCX by document_id. "
            "Use only when the file already exists in document storage. Do not use "
            "for web search results or raw HTML."
        ),
    },
    {
        "name": "extract_web_results",
        "description": (
            "Extracts title, URL, snippet, publication date, and source credibility "
            "from web_search results. Use only after web_search/web_fetch. Do not "
            "use for uploaded files or inline drafts."
        ),
    },
]

Risky: "Whenever the user mentions a document, call analyze_document."
Better: "When the user provides a stored document_id or file path, use analyze_uploaded_document.
When the user asks about search output or fetched web pages, use extract_web_results."

import anthropic
from dotenv import load_dotenv

load_dotenv()  # reads ANTHROPIC_API_KEY from your .env file

client = anthropic.Anthropic()

# Turn 1: force identity verification before anything else can happen.
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    tools=tools,
    tool_choice={"type": "tool", "name": "verify_identity"},
    messages=[{"role": "user", "content": "Refund my last order."}],
)

# ... append assistant tool_use and the tool_result for verify_identity ...

# Turn 2: identity is confirmed. Force a tool-based response (no chit-chat).
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    tools=tools,
    tool_choice={"type": "any"},   # must call SOME tool, model picks which
    messages=messages,
)

# DEFINE THE TOOLS
# Note: Use 'strict: True' for the CRM tool to guarantee valid JSON.
# Note: 'code_execution' must have a name even if it's a built-in server tool.

tools = [
    {
        "type": "web_search_20260209",
        "name": "web_search",
        "max_uses": 5,
        "allowed_domains": ["gartner.com", "forrester.com", "hbr.org"],
    },
    {
        "type": "code_execution_20260120",
        "name": "code_execution"   # CRITICAL: required alongside type
    },
    {
        "name": "add_lead_to_crm",
        "description": "Adds a validated prospect to the enterprise CRM. Use only after industry research is complete.",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "company": {"type": "string"},
                "contact_email": {"type": "string", "format": "email"},
                "budget_range": {"type": ["string", "null"]},   # Nullable to prevent hallucinations
            },
            "required": ["company", "contact_email", "budget_range"],
            "additionalProperties": False,
        },
    },
]

# THE INITIAL REQUEST
# On Opus 4.7, 'thinking' is required for complex tasks like this.
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=8192,
    thinking={"type": "adaptive"},
    tools=tools,
    messages=[{
        "role": "user",
        "content": "Find the top 5 AI consulting prospects in EMEA finance and add them to my CRM.",
    }],
)

# SHOW OUTPUT
print(f"Stop Reason: {response.stop_reason}")   # Expected: 'tool_use'
for block in response.content:
    if block.type == "thinking":
        print("Reasoning Signature Detected.")
    if block.type == "tool_use":
        print(f"Claude requested tool: {block.name}")
        print(f"Parameters: {block.input}")

def handle_tool_use(block):
    if block.name == "add_lead_to_crm":
        # crm.write(block.input)  # your client-side action
        return {
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": "ok: lead written",
        }
    raise ValueError(f"unhandled client-side tool: {block.name}")

# Loop until Claude is done.
while response.stop_reason == "tool_use":
    tool_results = [handle_tool_use(b) for b in response.content if b.type == "tool_use"]
    response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=8192,
        thinking={"type": "adaptive"},
        tools=tools,
        messages=[
            {"role": "user", "content": "Find the top 5 AI consulting prospects ..."},
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results},
        ],
    )

# FINAL OUTPUT VERIFICATION
# Web search automatically provides citations.
for block in response.content:
    if block.type == "text":
        print("Final Answer:", block.text)
        if hasattr(block, "citations") and block.citations:
            print("Sources:", [c.url for c in block.citations])