Tool Declaration 과 Schema

모델은 너 코드 못 읽어

Function calling 이 모델이 너 함수 실행하는 것처럼 들리는데 X. 모델은 너의 declaration 읽음 — 이름, description, 파라미터 schema — 그리고 너한테 호출해 달라는 구조화된 request emit. 너가 실행, 너가 결과 반환, 모델이 계속.

즉: 너가 작성하는 description 과 schema 가 모델이 너 tool 에 대해 아는 유일한 거. 문서가 아니라 API 계약.

OpenAPI subset, full JSON Schema 아님

Gemini 의 tool schema 가 OpenAPI 3.0 의 subset. JSON Schema 와의 차이가 중요:

Feature	Gemini (OpenAPI subset)	JSON Schema
Top-level type	항상 `"object"`	아무거나
`$ref` / `$defs`	지원 X	지원
`anyOf` / `oneOf`	지원 X	지원
`additionalProperties`	인식 X	지원
Enum	`enum` 배열 사용	같음
Nested object	지원	지원

번역: schema flat 하게 유지, ref X, union type X. 실제 tool 이 polymorphism 필요하면 별도 tool 들로 expose.

Description 이 이름보다 중요

모델이 description 읽고 tool 고름. do_thing + 좋은 description 이 queryEnterpriseAccountManagementSystem + 모호한 description 보다 outperform. 30 초 만에 훑을 동료에게 작성하는 docstring 처럼 description 작성.

Code

깔끔한 tool declaration·python

from google.genai import types

set_lights = {
    'name': 'set_light_values',
    'description': (
        'Adjusts the brightness and color temperature of a smart light. '
        'Brightness is a 0-100 integer percentage. Color temperature is one '
        'of "daylight" (5000K), "cool" (4000K), or "warm" (2700K).'
    ),
    'parameters': {
        'type': 'object',
        'properties': {
            'brightness': {
                'type': 'integer',
                'description': 'Brightness percent, 0-100.',
            },
            'color_temp': {
                'type': 'string',
                'enum': ['daylight', 'cool', 'warm'],
                'description': 'Color temperature preset.',
            },
        },
        'required': ['brightness', 'color_temp'],
    },
}

tools = types.Tool(function_declarations=[set_lights])

TypeScript 모양 — 같은 아이디어·typescript

import { Type } from '@google/genai';

const setLights = {
  name: 'set_light_values',
  description: 'Adjusts brightness (0-100) and color temperature (daylight/cool/warm).',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.INTEGER,
        description: 'Brightness percent, 0-100.',
      },
      color_temp: {
        type: Type.STRING,
        enum: ['daylight', 'cool', 'warm'],
        description: 'Color temperature preset.',
      },
    },
    required: ['brightness', 'color_temp'],
  },
};

Silent 하게 실패하는 패턴·python

# ❌ Top-level array — Gemini wants object
bad1 = {'name': 'log_events', 'parameters': {'type': 'array', 'items': {...}}}

# ❌ Union types via anyOf
bad2 = {
    'parameters': {
        'type': 'object',
        'properties': {
            'value': {'anyOf': [{'type': 'string'}, {'type': 'integer'}]}
        }
    }
}

# ❌ Refs
bad3 = {
    'parameters': {
        'type': 'object',
        '$defs': {'User': {...}},
        'properties': {'user': {'$ref': '#/$defs/User'}}
    }
}

# ✅ Flat the union into two tools instead
set_string_value = {'name': 'set_string_value', 'parameters': {'type': 'object', 'properties': {'value': {'type': 'string'}}, 'required': ['value']}}
set_int_value    = {'name': 'set_int_value',    'parameters': {'type': 'object', 'properties': {'value': {'type': 'integer'}}, 'required': ['value']}}

Exercise

실제로 쓰는 API 골라 (캘린더, 날씨 서비스, GitHub) tool declaration 2 개 작성. 동료가 너한테 안 묻고 정확히 호출할 수 있을 만큼 tight 한 description 작성하도록 강제. Flash 한테 자연어 prompt 로 사용 요청. 더듬으면 description 이 일 필요 — schema 아님.