probe_compaction

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, and the description reinforces and extends this by explaining that the tool does not compact and does not prove live compaction compatibility. The layout_compatible clarification and unsupported-standalone-session note add meaningful behavioral context beyond what annotations provide.

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?

Every sentence earns its place: the first states the tool's purpose, the second gives usage sequence, the third clarifies limitations, and the fourth handles unsupported cases and alternatives. The description is front-loaded with the most important information and contains no filler.

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?

The description covers purpose, sequencing, limitations, and unsupported environments, and even explains the meaning of layout_compatible despite there being no output schema. The only minor gap is that it does not explicitly describe the return value or result shape beyond that one field, though the preflight framing makes this less critical.

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 coverage is 100%, and the schema already fully explains threadId including the instruction to obtain it from the environment and never guess. The description adds no meaningful parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

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 clearly identifies the tool as a read-only preflight for an extension-owned Codex VS Code chat and lists the exact things it verifies: owner/thread, extension version, runtime layout, public schema, and IPC access. It also distinguishes itself by stating what it does not do and by referencing its position relative to sibling tools.

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?

The description gives explicit sequencing guidance: run after compaction_status and before schedule_compaction. It also states when not to use it, telling users that standalone Codex CLI sessions are unsupported and directing them to use compaction_status instead to inspect an existing job.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.