re_vm

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

Given no annotations are provided, the description carries the full behavioral burden. It discloses key operational details: compact defaults to TRUE, pagination has a default/max limit of 500/5000, and responses include has_more/total_matched. It also reveals alloc creates RWX memory regions, which is critical safety context. However, it omits error behavior and side effects for free/vquery.

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 description is extremely concise, front-loading the domain and then structuring each operation in a compact syntax. Every element (ops, parameter lists, defaults, pagination note) contributes value. The shorthand notation is dense but not wasteful, though the occasional ambiguous punctuation (e.g., question marks in braces) could be clearer.

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 tool has 10 parameters, four operations, and no output schema, so behavioral and return-value details are important. The description covers pagination and response fields for vad, but does not explain return formats for vquery, alloc, or free, nor how errors or invalid addresses are handled. While it is comprehensive for a terse reference, the lack of output schema means more return/error context would be expected.

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?

Although the input schema covers all parameters with descriptions (100% coverage), the description adds crucial semantics by mapping each operation to relevant parameters and noting defaults (compact TRUE, limit 500). It also documents response fields (has_more/total_matched) not present in the schema. This significantly helps an agent choose and fill parameters correctly for a multi-op tool.

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 this as a virtual memory tool and enumerates four distinct operations (vquery, vad, alloc, free), each with its own parameter list. This distinguishes it from sibling tools like re_read/re_write that handle memory directly, and the operation-specific syntax clarifies what the tool does, though the verb is implied rather than explicitly stated.

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?

No explicit guidance is given about when to use this tool versus alternatives. The description does not mention exclusions or preferred contexts, nor does it compare to sibling tools like re_read or re_scan. The only usage hints are the operation list, which implies the scope but does not state when this tool is the right choice.

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