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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely non-obvious traits beyond those: the output is deterministic and no additional LLM call is made, which tells the agent this is a cheap, reproducible read.

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?

Two tight sentences, front-loaded with the purpose and the deterministic/no-LLM caveat. No wasted wording, though slightly terse on scope/limits.

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?

With an output schema present, return values needn't be explained, and annotations cover the safety profile. The description covers purpose and default mode adequately; only explicit sibling differentiation is missing.

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 every parameter including mode, question, max_chars, and session_ref is already documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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?

States a specific verb+resource ('Return deterministic lexical context') and the selection input ('for a question'), which is clearer than a bare name restatement. It doesn't explicitly distinguish itself from siblings pi_session_search/pi_session_find/pi_session_read, so an agent must infer the boundary from the names alone.

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 notes the default behavior ('Defaults to useful conversation content'), and the mode param description covers conversation vs raw. But there is no explicit when-to-use-this vs the sibling session tools, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that only primary sessions are returned (nested subagent/artifact sessions excluded) and how to recover from a project-scoped miss, but says nothing about ordering, pagination behavior, or result shape beyond what the schema states.

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?

Two tight sentences, no filler. The core capability is front-loaded and the scope-retry caveat follows immediately, so an agent can act after one read.

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 4-parameter, fully documented, read-only lookup tool with an output schema, the description supplies the essential purpose and the one non-obvious operational decision (when to widen scope). Nothing critical is missing, though it could note the exact-match requirement relative to the fuzzy search sibling.

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 limit, cursor, scope and session_id are all documented in the schema itself. The description only re-touches scope's retry semantics, adding no syntax or format detail beyond the structured fields.

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?

States a specific verb, resource and matching mechanism: find primary Pi sessions whose filename ends in the supplied complete UUID. The 'primary' qualifier and exact-UUID matching distinguish it from the broader sibling pi_session_search.

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?

Gives an explicit condition for widening the search: 'Retry with scope all only when the UUID may belong to another project.' That is clear when/when-not guidance for the scoping parameter, though it never names pi_session_search as the alternative when the UUID is unknown or partial.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing that pages are stable and revision-bound (a consistent snapshot), which tells the agent reads won't shift under concurrent edits. It stops short of describing error or truncation behavior.

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?

Two sentences, zero filler, with the core read/pagination behavior front-loaded and the mode nuance second. Every clause carries information.

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?

With an output schema present, return values need not be described, and pagination plus mode are both covered. Minor gaps remain: what 'the active branch' means in this domain and ordering guarantees, but nothing essential for invoking the tool correctly is missing.

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%, with each parameter documented in the schema including the mode enum and cursor semantics. The description's mention of default vs raw mode restates what the schema already explains, adding no syntax or format detail beyond it. Baseline 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?

States a specific verb ('Read') and resource ('the active branch'), and clarifies that it returns stable, revision-bound pages rather than arbitrary data. It distinguishes itself functionally from siblings like pi_session_search/pi_session_find, but never names them, so the differentiation is implicit rather than explicit.

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 a default-versus-raw distinction ('Defaults to visible conversation content; raw mode includes metadata and tool internals'), which is a usage cue. However, it offers no guidance on when to prefer this tool over pi_session_context, pi_session_search, or pi_session_find, leaving sibling selection to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world behavior, so safety is covered. The description still adds real behavioral context: search is literal and case-insensitive, default scope is the active project with visible content only, and nested subagent/artifact sessions are excluded from results. It stops short of describing result ordering or match highlighting.

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?

Two dense sentences with no filler: the search semantics and the sibling alternative come first, then the scoping default and its exception. Front-loaded and every clause carries information.

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?

With an output schema present, return values need no explanation, and pagination via cursor is fully covered in the schema. The description covers scope defaults, content visibility, and the UUID edge case; only the relationship to the other read/context siblings is left implicit.

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 every parameter (mode, limit, query, scope, cursor) is already documented in the schema, including the enum guidance for mode and scope. The description echoes the scope-default guidance but adds no syntax or format detail beyond it, which is the baseline-3 case.

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?

States a specific verb and resource (literal case-insensitive search across primary Pi session histories) plus a notable edge case (complete session UUIDs are recognized) and explicitly routes UUID lookups to pi_session_find. An agent can distinguish this from its siblings without opening a schema.

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?

Gives clear context: defaults to the configured scope and visible conversation content, and warns to use scope all only for explicit cross-project recall. It names pi_session_find as the more direct alternative for UUID lookup. It does not, however, state when pi_session_context or pi_session_read should be used instead, so the routing guidance is partial.

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