liveBook · Manning

Tool definition

As explained in Designing AI Systems

ToolDefinition is the example request structure that describes a function an AI model may call, including its function metadata and parameter schema.

A tool definition is a typed contract describing an action an AI model may request. Its schema identifies the function, documents its parameters, and represents those parameters as JSON Schema. In a model request, ToolDefinition wraps FunctionDef; the workflow executes any resulting tool call and continues the conversation. section 3.1.6

Production systems extend the model-facing schema with platform metadata. Identity supports ownership, versioning, discovery, and access control; operational fields support guardrails, execution policy, rate limits, cost attribution, and retry decisions. section 6.1.2

A complete definition can expose several layers:

  • Schema: name, description, parameter definitions, and return definitions passed to model function-calling contexts. section 6.1.2
  • Identity: name, version, and owner establish a registry entity with a version history. section 6.1.2
  • Behavior: read-only, idempotent, confirmation, latency, and side-effect declarations inform safe execution and retry handling. section 6.1.2
  • Controls: permissions, capabilities, endpoints, credential references, rate limits, execution limits, and billing metadata connect the tool to platform operations. section 6.1.2

Model request versus managed tool

A chat request may define a check_availability function with a description and parameter schema. A production registration additionally records its owner, version, endpoint, permissions, read-only status, idempotency, rate limits, and estimated cost. The Tool Service can validate arguments, inject credentials, execute the external call, and return standardized results without exposing secrets to the application. section 3.1.6 section 6.1.1

Listing 6.2 Tool definition with identity and schema
message ToolDefinition {
  string name = 1;    #A
  string version = 2;    #B
  string owner = 3;    #C
 
  string description = 4;    #D
  string parameters_json = 5;    #D
  string returns_json = 6;    #D
 
  ToolBehavior behavior = 7;
  RateLimits rate_limits = 8;
  CostMetadata cost = 9;
  repeated string required_permissions = 10;
  repeated string capabilities = 11;
  repeated string tags = 12;
  string endpoint = 13;
  string credential_ref = 14;
  ExecutionLimits execution_limits = 15;
}

Use the complete definition to inspect how model-facing schema fields coexist with identity, permissions, endpoints, credentials, limits, and operational metadata. section 6.1.2

How Designing AI Systems covers it

How deep it goes
Explains nested schemas, governance metadata, and managed execution, stopping short of provider-specific implementation details.
Examples
Uses check_availability and book_appointment to contrast read-only and state-changing tools, alongside Protocol Buffer definitions.
What it assumes
Assumes familiarity with model function calling and JSON Schema while establishing production metadata and service operations explicitly.
What you can do after
Build tool contracts, register them, validate arguments, and delegate credentialed synchronous or asynchronous execution through a Tool Service.
How it connects
Connects function calling with JSON Schema, guardrails, access control, rate limiting, credential injection, and MCP servers.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.