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
