[DOCS] Missing Security Guidance and Input Validation in Custom Tools Examples

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/custom-tools

Section/Topic

The "Example Tools" section, specifically the "Database Query Tool" and "API Gateway Tool" implementations.

Current Documentation

The documentation provides code examples that directly pass model-generated arguments into high-privilege functions.

TypeScript Example (Database Query Tool):

async (args) => {
  const results = await db.query(args.query, args.params || []);
  return {
    content: [{
      type: "text",
      text: `Found ${results.length} rows:\n${JSON.stringify(results, null, 2)}`
    }]
  };
}

Python Example (API Gateway Tool):

@tool("api_request", "Make authenticated API requests...", {...})
async def api_request(args: dict[str, Any]) -> dict[str, Any]:
    # ... logic ...
    url = f"{service_config['base_url']}{args['endpoint']}"
    # ...
    async with aiohttp.ClientSession() as session:
        async with session.request(args["method"], url, ...)

What's Wrong or Missing?

The examples demonstrate unvalidated execution of model-generated strings.

Because the args are generated by an LLM, they are susceptible to prompt injection or "jailbreaking."

• In the Database Query Tool, the model is given direct control over the SQL string (args.query). Without a warning or validation logic, a user could trick the agent into executing DROP TABLE or exfiltrating sensitive data via UNION SELECT.
• In the API Gateway Tool, the model has control over the endpoint and method. This presents a Server-Side Request Forgery (SSRF) risk or an unauthorized path traversal risk if the model is manipulated to access administrative endpoints (e.g., /admin/delete_user).

While the "Secure Deployment" page exists elsewhere, these specific implementation examples lack immediate "Warning" callouts or patterns for input sanitization.

Suggested Improvement

Add a "Security Best Practices" callout to the Custom Tools page and update the examples to include basic validation logic.

Suggested text for a Warning block:

⚠️ Security Warning: Tools execute with the privileges of your application. Since tool arguments are generated by the model, you must treat them as untrusted input. Always validate, sanitize, or allowlist inputs—especially for database queries, API endpoints, and filesystem paths.

Suggested improvement to the Database Example:
Show a pattern for restricted query access:

async (args) => {
  // Example of basic validation
  if (!args.query.trim().toLowerCase().startsWith("select")) {
    throw new Error("Only read-only SELECT queries are permitted.");
  }
  const results = await db.query(args.query, args.params || []);
  // ...
}

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: The Securely deploying AI agents page correctly identifies these risks, but developers often copy-paste from the "Custom Tools" implementation guide without visiting the security overview first.
• Example from other projects: The Model Context Protocol (MCP) official SDK documentation explicitly mentions that server authors are responsible for validating arguments. Linking to that or mirroring that emphasis would be beneficial.