Skip to content

docs: add terminology guide#130

Merged
jiahuei merged 1 commit into
mainfrom
agent/add-terminology
Jul 16, 2026
Merged

docs: add terminology guide#130
jiahuei merged 1 commit into
mainfrom
agent/add-terminology

Conversation

@jiahuei

@jiahuei jiahuei commented Jul 16, 2026

Copy link
Copy Markdown
Collaborator

With agents expected to perform much of this repository's development, this PR establishes shared terminology to
guide their wording in code and pull requests and keep maintainers and contributors aligned on the meaning
of core concepts.

The guide aligns project vocabulary with current OpenAI documentation while preserving project-specific terms where
the implementation has a distinct concept. In particular, it separates OpenAI tool categories from execution
location: new prose should use terms such as built-in tool, gateway-executed built-in tool,
client-executed function tool, and upstream-hosted built-in tool instead of the ambiguous
gateway/client/provider-owned vocabulary.

Summary

  • Add TERMINOLOGY.md with a list of accepted terms and definitions.
  • Cover Responses API objects and state, tool calling, MCP, streaming transports and events, reasoning, and runtime
    boundaries.
  • Add a preferred-wording table for recurring terminology conflicts, including:
    • built-in tools versus gateway-owned tools
    • tool call outputs versus tool results
    • item history versus message history
    • semantic streaming events versus streaming chunks
  • Distinguish a user-visible turn from an internal inference round, including the active-turn reasoning distinction
    relevant to tool loops.
  • Preserve exact vocabulary when discussing other wire protocols, such as Anthropic tool_use and tool_result.
  • Reference TERMINOLOGY.md from AGENTS.md and make it normative for future project prose.
  • Link the official OpenAI documentation used as the terminology source.

Test Plan

Validated with:

cargo fmt -- --check
git diff --check
uvx pre-commit run --files AGENTS.md TERMINOLOGY.md

Signed-off-by: Tan Jia Huei <tanjiahuei@gmail.com>
@jiahuei
jiahuei merged commit 9d5a1fc into main Jul 16, 2026
3 checks passed
@jiahuei
jiahuei deleted the agent/add-terminology branch July 16, 2026 12:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants