Kimi API Official Tools let an application discover a Moonshot-hosted Formula, ask Kimi to choose its function, execute that function through a Fiber, and return the result to the model for a final answer. This is a different integration from developer-defined Kimi API tool calling: your application still controls the loop, but Moonshot hosts the Formula execution layer.
We ran three low-risk Formula chains with kimi-k3: unit conversion, a UTC weekday lookup and Base64 encoding. All 3/3 chains completed, but only 2/3 final answers matched the frozen oracles. The date chain returned Friday instead of Tuesday. Its trace shows that K3 chose operation: "time", which the fetched declaration describes as “show time,” before the Fiber returned Friday. The evidence does not isolate whether the mismatch came from K3’s operation choice, the Formula’s handling of the supplied date, or ambiguity in the tool contract.
Independent test result, August 7, 2026: Run
official-tools-20260807173429completed three sequential, single-pass cases with zero retries. Convert and Base64 passed. Date failed. Usage-derived K3 inference cost was $0.0153414. We did not use Web Search, OAuth, account data, persistent memory, fetch, code execution or any non-allowlisted Formula.
Kimi AI Guide is independent and is not affiliated with Moonshot AI or Kimi.
Our result at a glance
| Frozen case | Formula | Tool/Fiber output | Final K3 answer | Oracle | Result |
|---|---|---|---|---|---|
| Convert 2.5 meters to centimeters | moonshot/convert:latest | 2.5 meter = 250 cm | 250 cm | 250 cm | Pass |
Weekday for 2030-01-01 in UTC | moonshot/date:latest | Friday | Friday | Tuesday | Fail |
Base64-encode KI-AI-2026 as UTF-8 | moonshot/base64:latest | S0ktQUktMjAyNg== | S0ktQUktMjAyNg== | Same exact string | Pass |
There are two separate scores:
- Chain completion: 3/3. Each case fetched a declaration, received one K3 tool call, completed one Fiber and received one final K3 answer.
- Factual accuracy: 2/3. Only the convert and Base64 answers matched their independently calculated oracles.
This distinction matters in production. HTTP 200, status: succeeded and a syntactically valid final answer can coexist with an incorrect result.
How Kimi Official Tools work
Kimi’s Official Tools guide describes a Formula flow with four participants:
| Participant | Responsibility |
|---|---|
| Your application | Chooses an allowlisted Formula, fetches declarations, validates the returned call, executes one Fiber and controls limits |
| Kimi model | Selects a declared function and arguments, then writes the final answer after receiving the tool result |
| Formula | Defines the hosted function and parameter schema |
| Fiber | Executes one Formula call and returns its status and output |
The minimum safe sequence is:
- Fetch the Formula’s current tool declaration from
/v1/formulas/{formula_uri}/tools. - Send that declaration to
POST /v1/chat/completionswith a narrow user task. - Require exactly one returned function whose name exists in the fetched declaration.
- Parse and validate
function.argumentsas untrusted JSON. - POST the exact function name and arguments once to
/v1/formulas/{formula_uri}/fibers. - Require a succeeded Fiber, but do not assume the output is factually correct.
- Append the complete assistant tool-call message to the conversation.
- Append one
role: "tool"message with the matchingtool_call_idand Fiber output. - Send one bounded continuation request and validate the final answer for your domain.
Our test fetched declarations separately for convert, date and base64; it did not copy a stale schema into the live request.
Formula tools versus custom function tools
| Question | Kimi Official Tool / Formula | Developer-defined function tool |
|---|---|---|
| Who hosts execution? | Moonshot’s Formula/Fiber service | Your application or service |
| Where does the schema come from? | Fetched from the Formula tools endpoint | Written and versioned by you |
| Who authorizes side effects? | Your app must still gate Formula access; Formula-specific controls may also apply | Your application entirely |
| Can the output be wrong? | Yes – our date case demonstrates this | Yes – your handler, data source or model loop can fail |
| Does a model call the tool by itself? | No; your application orchestrates the Fiber request | No; your application dispatches the handler |
Use the custom tool-calling guide when you own the function. Use this page when the selected capability is exposed as a Kimi Formula.
A bounded implementation pattern
The following JavaScript-style outline shows the control boundaries. It is deliberately incomplete: production code still needs timeouts, HTTP error handling, schema validation, logging redaction and a spend limit.
const formulaUri = "moonshot/convert:latest";
// 1. Discover the live declaration.
const declaration = await kimiGet(
`/v1/formulas/${formulaUri}/tools`
);
// 2. Ask K3 for exactly one declared tool call.
const first = await kimiChat({
model: "kimi-k3",
reasoning_effort: "low",
max_completion_tokens: 512,
messages: [systemMessage, userMessage],
tools: declaration.tools,
tool_choice: "required"
});
const assistant = first.choices[0].message;
const call = requireOneAllowlistedCall(assistant, declaration.tools);
const args = validateArguments(call.function.arguments);
// 3. Execute the exact approved call once.
const fiber = await kimiPost(
`/v1/formulas/${formulaUri}/fibers`,
{ name: call.function.name, arguments: JSON.stringify(args) }
);
if (fiber.status !== "succeeded") throw new Error("Formula did not succeed");
// 4. Preserve the complete assistant message and call linkage.
const final = await kimiChat({
model: "kimi-k3",
reasoning_effort: "low",
max_completion_tokens: 512,
messages: [
systemMessage,
userMessage,
assistant,
{
role: "tool",
tool_call_id: call.id,
content: fiber.context.output
}
],
tools: declaration.tools,
tool_choice: "none"
});Do not dispatch a model-supplied Formula URI, function name or arguments without an application allowlist. A valid declaration does not grant the user permission to invoke every available operation.
Test methodology
We froze the protocol, prompts, oracles, model, output limits and cost ceiling before the first response.
| Setting | Frozen value |
|---|---|
| Run ID | official-tools-20260807173429 |
| Date | August 7, 2026 |
| API region | Global, https://api.moonshot.ai/v1 |
| Model | kimi-k3 |
| Reasoning effort | low |
| Maximum completion | 512 tokens per model call |
| Formula allowlist | convert, date, base64 only |
| Cases | 3 synthetic, deterministic tasks |
| Execution | Sequential, one chain per case |
| Retries or corrective reruns | 0 |
| Web Search / OAuth | Not used |
| Scoring | Exact or regex oracle after the final answer |
For each case, the runner performed exactly one declaration fetch, one first K3 completion, one Fiber execution and one final K3 continuation. The complete assistant tool-call message and matching tool result were retained. K3 reasoning text, credentials and provider/account identifiers were removed from the public traces.
The tasks were selected because their answers can be verified independently without personal data, changing web content or third-party accounts.
Case 1: conversion passed
The frozen prompt asked the tool to convert 2.5 meters to centimeters and return only the value and unit.
K3 selected:
{
"name": "convert",
"arguments": {
"value": 2.5,
"from_unit": "meter",
"to_unit": "cm"
}
}The Fiber returned 2.5 meter = 250 cm; the final model answer was 250 cm. Both match the arithmetic oracle, so the case passed.
Case 2: the date chain failed, but the cause is not isolated
The frozen task was: determine the weekday for 2030-01-01 in UTC and return the weekday only. The fetched declaration described the date tool as supporting current-time display, timezone conversion and date calculations. Its operation field listed time as “show time”; it did not expose a separate weekday operation.
K3 selected the date function with:
{
"operation": "time",
"date": "2030-01-01",
"zone": "UTC",
"format": "%A"
}The Fiber reported status: succeeded and returned Friday. That is also the weekday of the run date, August 7, 2026. K3 then received Friday as the tool message and returned Friday as its final answer.
The frozen UTC oracle is Tuesday. This can be reproduced locally without Kimi:
const weekdays = [
"Sunday", "Monday", "Tuesday", "Wednesday",
"Thursday", "Friday", "Saturday"
];
const date = new Date("2030-01-01T00:00:00Z");
console.log(weekdays[date.getUTCDay()]); // TuesdayThe chain failed its oracle, but the trace does not prove a Formula defect. At least three explanations remain consistent with the evidence:
- K3 may have selected an operation that did not match the requested historical-date task;
- the Formula may have handled or ignored the supplied
dateunderoperation: "time"; or - the declaration may be ambiguous about whether
timeaccepts a supplied date with%Aformatting.
The trace does show that the final formatting step preserved the Fiber output rather than correcting it. We did not rerun the case, change the operation or probe alternative arguments after seeing the failure, so root cause remains unresolved.
This one case does not establish a date Formula defect or a general error rate. It does establish that applications should validate both the model-selected operation and the returned result rather than treating succeeded as a correctness guarantee.
Case 3: Base64 passed
The frozen task asked for UTF-8 Base64 encoding of KI-AI-2026. K3 selected:
{
"name": "base64",
"arguments": {
"data": "KI-AI-2026",
"encoding": "utf-8"
}
}The Fiber and final answer both returned S0ktQUktMjAyNg==. A local Buffer.from(text, "utf8").toString("base64") oracle returned the same exact value, so the case passed.
Usage and cost
The table below uses token counts returned by the two K3 completions in each case and the price table frozen for this run. It is a usage-derived calculation, not proof that the account console posted the charge immediately.
| Case | First K3 call | Final K3 call | Calculated total |
|---|---|---|---|
| Convert | $0.0033030 | $0.0017658 | $0.0050688 |
| Date | $0.0038040 | $0.0019608 | $0.0057648 |
| Base64 | $0.0027840 | $0.0017238 | $0.0045078 |
| Total | $0.0098910 | $0.0054504 | $0.0153414 |
Across the six K3 requests, the API reported 3,170 prompt tokens, including 768 cached tokens, and 527 completion tokens. The official guide described these Formula executions as temporarily free when checked on August 7, 2026; K3 inference remained billable. Tool availability and pricing can change, so check the live Kimi API pricing and limits before designing a budget.
What the test does not prove
- Three single-pass cases are not a reliability benchmark or an uptime measurement.
- Only
kimi-k3and three low-risk Formula tools were tested. - Web Search was deliberately excluded; this page does not test its accuracy, citations, fee or current availability.
- No OAuth connection, user account, external data, write action or sensitive file was used.
- No malformed declaration, Fiber timeout, rate limit, partial response or concurrent call was injected.
- The final answers were short and deterministic; longer synthesis may fail in different ways.
- Pricing and Formula definitions are dated observations and may change.
The defensible conclusion is: these three Formula chains completed once; two final answers matched their oracles and one date chain did not. The failing trace does not isolate the responsible layer. It is not defensible to claim a Formula defect, or that Kimi Official Tools are universally accurate or production-reliable, from this sample.
Production safeguards
- Maintain a server-side allowlist of Formula URIs and function names.
- Fetch and validate the current declaration before use; do not trust an old copied schema indefinitely.
- Treat every model-supplied argument as untrusted input.
- Enforce user authorization separately from tool selection.
- Set request, Fiber, round, output-token and total-spend limits.
- Never retry a write-capable Formula blindly after an uncertain transport failure.
- Validate important outputs against a deterministic rule or authoritative source.
- Preserve the full assistant tool-call message and exact
tool_call_idlinkage. - Log sanitized status, usage and timings, not API keys, OAuth tokens, reasoning text or account identifiers.
- Require human confirmation before destructive, external or billable side effects.
For app-owned functions, continue with Kimi API Tool Calling. For authentication and a first request, start with the Kimi API guide. Use the Kimi API Error Decoder for bounded failure handling.
Official source and evidence boundary
- Kimi Official Tools guide – vendor-documented Formula discovery, Fiber execution and continuation flow.
- Kimi API models – current model identifiers and availability.
- Kimi API pricing and limits – current account and billing requirements.
All result tables, costs and failure analysis on this page come from the sanitized public artifacts for run official-tools-20260807173429, not from vendor marketing. The public trace keeps tool declarations, exact function arguments, Fiber outputs, final answers, usage and scores while excluding credentials, account financial state, rate-limit state, unredacted account/provider identifiers and K3 reasoning text.
The Kimi API Official Tools Evidence Bundle is 14,262 bytes with SHA-256 30F98279FEE09641B655B6F104F87C5FB6D1C3236AF94D4EC9F470CEF636A97D. Its internal manifest records every evidence file, its secret-and-financial-state scan passed with zero findings, and a fresh public download matched the local byte count and hash exactly.