dosbox_find_cave

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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds behavioral detail beyond that: it returns zero-run candidate gaps, orders them longest first, and indicates the guest segment context. It does not cover edge cases such as 'no suitable cave found', but the existing annotation and output schema partly mitigate that.

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?

Three short sentences, each signing significant value: what the tool does, where the supply is typically found, and how to use the result. The key behavioral constraint ('longest first') is front-loaded and the follow-up call is clearly mentioned. There is no redundant 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?

For the task of finding and using a trace cave, the description is essentially complete: it explains the search target, ordering, and next action. The only missing nuance is handling the pid parameter and the absence of an explicit failure case, but these are minor because the schema and output schema clarify the interface.

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 67%, with segment and bytes_needed already described in the schema. The description reinforces that bytes_needed corresponds to the amount of room the cave needs, but it does not explain the pid parameter, which has no schema description. Overall, the description adds only modest parameter-level value beyond 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 the exact operation: 'Find runs of zero in a guest code segment long enough to hold a trace cave.' It clearly identifies the resource (guest code segment), the condition (runs long enough), and the intended purpose (a trace cave). It also references the downstream sibling tool dosbox_install_trace, so an agent can distinguish it from read/search/memory 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 provides actionable guidance: 'Padding between routines is the usual supply' tells where to look, and 'Longest first; pass one of these offsets to dosbox_install_trace' tells what to do with the result. It names the immediate sibling for the follow-up action, though it does not explicitly state when not to use this tool or describe alternative routes.

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