open_pit

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

Annotations already provide readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful lifecycle context: PIT freezes the data view, is held by the cluster for a time controlled by keep_alive, and must be explicitly closed. This goes beyond the structured hints, though it does not detail side effects like resource usage or closure behavior after timeout.

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 concise: two sentences, no filler, and front-loaded with the primary function. It packs in the pagination motivation, pair with paged_search, close_pit requirement, and the semantics of keep_alive without waste.

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?

Given the tool has only two parameters, uses existing annotations, and has an output schema available, the description supplies the critical integration logic: why to open it, how it supports pagination, and the mandatory close_pit call. All needed operational context is covered succinctly.

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 0%, so the description must carry parameter meaning. It covers keep_alive explicitly ('controls how long ES holds it open') and states that index is the target of the PIT. The descriptions are useful and disambiguate the meaning of both parameters, though the index parameter is only implicit in 'against an index' rather than explicitly labeled.

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?

Description states a specific verb ('Open'), a specific resource ('a point-in-time (PIT) against an index'), and the desired result ('return its pit_id'). It also distinguishes itself from related tools like paged_search and close_pit within the description, so an agent understands the tool's exact role.

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 clearly explains when open_pit is useful: for consistent pagination past the 10000-depth limit with paged_search. It also provides explicit guidance to always pair it with close_pit. It does not explicitly state when not to use it (e.g., for one-shot queries), so it misses the full when-not/exclusion aspect.

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