json// Claude's response, stop_reason "tool_use"
{ "type": "tool_use", "id": "toolu_01A", "name": "get_weather",
  "input": { "location": "San Francisco, CA" } }

// Your next request, role "user"
{ "type": "tool_result", "tool_use_id": "toolu_01A",
  "content": "15 degrees celsius, partly cloudy" }

// When the tool fails
{ "type": "tool_result", "tool_use_id": "toolu_01A",
  "is_error": true, "content": "API timeout after 30 seconds" }

1. One response can hold text and several tool_use blocks.
2. Several calls → several tool_result blocks in one message, each matching its id.
3. is_error: true tells Claude the tool failed so it can reason about recovery.

json{ "content": [
  { "type": "tool_use", "name": "Agent",
    "input": { "prompt": "Search for recent papers on...",
               "subagent_type": "search" } },
  { "type": "tool_use", "name": "Agent",
    "input": { "prompt": "Analyze the document at...",
               "subagent_type": "analysis" } }
] }

1. Both calls in a single coordinator response run in parallel. Separate turns run sequentially.
2. The coordinator needs Agent in its allowed tools. Agent(worker, researcher) narrows the types.
3. Older material, including the exam guide, calls it the Task tool. Same mechanism.

json{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Customer identity not yet verified",
    "additionalContext": "Call get_customer first to verify identity"
  }
}

1. Decisions are allow, deny, ask and defer. When hooks disagree, deny wins.
2. A command hook passes with exit 0 and blocks with exit 2.
3. A hook's allow never overrides a matching deny permission rule.
4. By default a hook that fails to start or times out lets the action go ahead. Make policy gates fail closed.

json{
  "name": "extract_invoice",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "vendor_name": { "type": "string" },
      "total_amount": { "type": "number" }
    },
    "required": ["vendor_name", "total_amount"],
    "additionalProperties": false
  }
}

1. strict: true guarantees Claude's tool inputs conform exactly to the schema.
2. additionalProperties: false must be set.
3. Every property must be listed in required.
4. Only a subset of JSON Schema is supported (Domain 4).

json{
  "mcpServers": {
    "shared-api": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

1. ${VAR} expands from the environment, so the secret is never in the file. ${VAR:-default} covers unset ones.
2. command + args start a stdio server; remote entries set type and url.
3. Interactive sessions ask before using project servers; claude -p and Agent SDK runs load them without asking.
4. Remote auth: OAuth via /mcp, else a static token in headers, or headersHelper for short-lived ones.

markdown# CLAUDE.md
@AGENTS.md
@docs/coding-standards.md
@~/.claude/my-personal-preferences.md

See @README.md for project overview.

## Claude-specific overrides
Use plan mode for changes under `src/billing/`.

1. Relative paths resolve from the file that holds the import; @~/ is your home directory.
2. Imported files can import too, up to a depth limit that stops circular imports.
3. No CLAUDE.md in the project? Claude Code falls back to reading AGENTS.md.
4. A personal CLAUDE.local.md counts as having one and silently stops AGENTS.md loading. Import it with @AGENTS.md.

yaml---
name: deploy
description: Deploy the application to a specified environment
context: fork
agent: Explore
allowed-tools: Bash(git *) Bash(npm run deploy *)
argument-hint: [environment]
disable-model-invocation: true
---

Deploy the application to $ARGUMENTS.

1. description is how Claude decides whether to auto-load the skill.
2. disable-model-invocation: true means only the user can run it. user-invocable: false hides it from the menu instead.
3. context: fork runs it in an isolated subagent, chosen by agent. CLAUDE.md loads; chat history doesn't.
4. allowed-tools pre-approves tools for the invoking turn only. $ARGUMENTS is what the user typed.

yaml---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.test.ts"
---

# API Development Rules

All API endpoints must:
- Use Zod for request validation
- Return standardized error responses
- Include rate limiting middleware

1. Rules live in .claude/rules/, one topic per file: testing, API design, security.
2. No frontmatter means the rule loads unconditionally at session start.
3. With paths, it loads when Claude reads, writes or edits a matching file.
4. Skills take the same paths field to auto-load only for matching files.

json{
  "name": "extract_invoice_data",
  "description": "Extract structured data from an invoice document",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "vendor_name": { "type": "string" },
      "total_amount": { "type": "number" }
    },
    "required": ["vendor_name", "total_amount"],
    "additionalProperties": false
  }
}

1. The input_schema is the structure you want back.
2. strict: true guarantees the output matches it.
3. Strict mode needs additionalProperties: false and every property listed in required.
4. Some current models reject forced tool_choice with a 400. There, use output_config.format, or auto plus strict: true.

pythonmax_retries = 3

for iteration in range(max_retries):
    response = extract_data(document, prompt)
    errors = validate(response)
    if not errors:
        return response  # success
    prompt += f"""
    Your previous extraction had these validation errors:
    {json.dumps(errors, indent=2)}
    Please correct these specific issues and try again.
    """

raise ExtractionError(f"Failed after {max_retries} attempts")

1. Validate every response and return the first clean one.
2. Schema checks catch missing fields, wrong types and bad enums. Sums, dates and cross-field contradictions need custom logic.
3. Extract a stated and a calculated total side by side to detect conflicts automatically.
4. Cap the attempts and raise when they run out.

textCASE FACTS (do not summarize):
- Customer ID: #12345
- Order: #67890
- Order date: 2024-01-15
- Total: $149.99
- Issue: Damaged product on arrival
- Refund requested: Full refund ($149.99)

1. Summaries round things off: $149.99 becomes “approximately $150”, 2024-01-15 becomes “mid-January”.
2. Order numbers, customer IDs, reference codes and exact error messages get lost too.
3. Extract them into a persistent structured block that survives summarization.
4. No compaction mechanism protects exact numbers better than restating them.