record_plugin_callsRecord actual plugin tool call attempts in batches, including failures, with stable call IDs for retries. Use it to log only executed calls, not discoveries, plans, or historical backfills.
实际调用插件工具后就近合批记录，每项一次调用尝试（失败也计）；id 使用调用 ID 或事先生成的 UUID，记录重试沿用，新的实际调用使用新 ID。plugin 为工具所属插件命名空间，如 github；tool 为完整 mcp__codex_apps__github_get_repo 名称。仅记录已发生调用，不记录发现、计划或历史补记。不传参数或结果正文，与 Skill 采用分开。
| Name | Required | Description | Default |
|---|---|---|---|
| calls | Yes |
Changes observed during successful MCP inspections.
v0.4.6Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring a non-read-only, non-destructive, closed-world write, the description still adds real behavior: batch-at-source recording, one record per attempt even on failure, retry semantics (reuse the id), new id for new invocations, and an explicit note that it does not capture parameters or result bodies. It doesn't say what happens if the batch partially fails or whether writes are atomic, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The sentences are dense and front-loaded, starting with the action and scope before the id and field rules. It is a little packed for one paragraph, but every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter write tool with no output schema, it covers what to record, what not to record, and the identity rules. Gaps around partial-batch failure, ordering, and response behavior are minor but real.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the load, and it does: id is a call ID or a pre-generated UUID reused on retry, plugin is the tool's namespace (e.g. github), and tool is the full mcp__codex_apps__github_get_repo name. That gives meaning beyond the patterns in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it records actual plugin tool invocations in batches at the nearest point, with one record per call attempt. It also distinguishes itself from sibling record_skill_use ("与 Skill 采用分开"), so an agent can route calls between the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit negative scope: only calls that actually happened are recorded, never discovery, planning, or retroactive/backfill entries. It also separates this from Skill recording, so the choice between siblings is stated rather than inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.