omni_session

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

With no annotations supplied, the description carries the full burden, and it does disclose the key trait that state persists across turns and that annotations are durable. It omits important behavior: session lifetime/expiry, whether session_id is required for every action after open, and what happens when an unknown or stale session is referenced.

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?

A single front-loaded sentence with the identity of the tool first and its capabilities after; no filler. It is dense but readable, and nothing is redundant with the schema.

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 six-parameter, multi-action stateful tool with no annotations and no output schema, the definition covers the what but not the mechanics: action-to-parameter requirements, session lifecycle, and return shape are left unstated. Adequate to select the tool, thin for invoking it correctly on the first try.

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 100%, so the baseline is 3. The description adds a little meaning by tying actions to outcomes (open projects, persist bookmarks/comments/renames, query state), but it does not clarify which parameters each action requires or how 'get' versus 'list' differ in output.

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 names a specific resource (stateful reverse engineering session) and enumerates the concrete operations it covers: opening binary projects, persisting bookmarks/comments/renames, and querying analysis state. An agent can distinguish it from siblings like omni_export_annotations or omni_inspect_symbol, though the sibling differentiation is implicit rather than 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?

'Across turns' implies this is the tool to reach for when continuity between calls matters, but the description never says when to use it versus omni_export_annotations for annotation handling, nor does it state that 'open' must precede 'annotate'. Usage is inferable from the action list but not spelled out.

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