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

With no annotations, the description carries full responsibility. It is exceptionally transparent: it states it is a 'pure fold' with 'no re-parsing', details how missing/empty group_by values bucket under '(unknown)', explains the exact folding behavior for tokens and component_tokens including provenance counters and the rule that absent components stay absent (never fabricated 0). It also describes the error return format. This goes far beyond what annotations would typically provide.

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?

Although lengthy, every sentence earns its place. The description is front-loaded with purpose, then uses a structured Args/Returns layout. The detailed explanations of metrics are necessary for correct usage and are not redundant. The structure is logical and the density is appropriate for the tool's complexity.

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's complexity (5 parameters, two complex metric types, multiple ordering options) and the fact that an output schema exists, the description is remarkably complete. It covers return format, edge cases, parameter constraints, and error conditions. It even specifies the ordering of groups for each rank_by option. There are no gaps that would leave an agent guessing.

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 compensate, and it does thoroughly. It explains rows (what counts as valid input), group_by (valid values and unknown handling), metrics (allowed values, default, and detailed behavior for nested token/component_tokens structures), rank_by (both options and their ordering), and kind_split (what happens when True). This provides full semantic clarity for all 5 parameters.

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 opens with 'Roll a list of row dicts up by group_by — the generic stats verb', which clearly states the action (rolling up rows) and resource (row dicts). It further distinguishes itself by noting it reproduces session_stats and file_frequency, making its purpose distinct from sibling tools. The purpose is specific and well-differentiated.

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 clear context on when to use the tool: it operates on already-materialized rows from query output, find_file_edits records, or a session inventory, and avoids re-parsing. It references session_stats as a thin preset, implying a relationship. However, it does not explicitly state when not to use this tool or name alternative tools outside of session_stats/file_frequency, so it lacks explicit exclusions.

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?

With no annotations provided, the description carries full behavioral burden and succeeds: it discloses the deterministic budget algorithm, the fixed truncation ladder, that user turns are NEVER truncated, error handling for invalid/ambiguous prefixes, redaction behavior, and the response structure. This is far beyond basic expectations.

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 long but front-loaded with a clear purpose and well-organized into sections with bullets. Every sentence provides useful detail, though there is slight redundancy (e.g., mentioning both 'preset' and 'thin wrapper') that could be trimmed without losing meaning.

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's complexity, the description is remarkably complete: it covers all parameters, behavioral edge cases, error mapping, output sections, and even the CLI mirror. The presence of an output schema doesn't reduce the need for this context because the tool's behavior around budgets and redaction is essential for correct invocation.

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 0%, but the description thoroughly explains all four parameters: session accepts full UUID or prefix, agent is an optional hint, redact masks secrets, and budget_chars drives the truncation algorithm. It adds operational meaning well beyond the bare schema definitions.

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 states the tool's purpose as a 'Token-lean, budgeted session digest for auditors' and explains it answers 'what happened in this session, verbatim where it matters'. It distinguishes itself from siblings by labeling itself a preset over the core, not a second engine, and by detailing its specific output structure.

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 specifies the intended use case ('for auditors') and clarifies it is a 'preset over the existing core' with a budget algorithm. However, it does not explicitly state when to prefer this over alternatives like read_session or session_stats, nor does it provide exclusions or alternative guidance.

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?

With no annotations, the description carries full burden and does so thoroughly. It explains the data sources (env vars + flag files), the candidate cascade, and the 'never guessed' behavior for model, and clarifies that resume_command is text-only and never executed. It also discloses error behavior for unknown agent hints.

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 well-structured with Args and Returns sections. Every sentence contributes: it defines the tool, contrasts with session queries, explains the parameter, enumerates return fields, and documents error cases. There is no filler or redundancy.

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?

Despite having an output schema, the description independently lists every return field and their semantics, including null cases and the error response. It gives enough context for the agent to invoke the tool correctly and interpret results without further lookup.

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 0%, but the description fully explains the single 'agent' parameter: it's an optional hint, accepted for symmetry with a deprecated CLI flag, and the cascade scans all agents. This adds meaning beyond the bare schema and leaves no ambiguity.

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 opens with a specific verb+resource: 'Return the current runtime identity (session + agent) from env/fs.' It clearly distinguishes itself by stating 'NOT a session-query,' which differentiates it from sibling tools like list_sessions and read_session.

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?

It explicitly states when not to use it ('NOT a session-query') and clarifies the underlying mechanism ('reads the runtime environment (env vars + per-session flag files)'), which tells the agent this is for runtime detection rather than persistent session queries. It also references CLI subcommands, aiding alignment with existing patterns.

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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that bodies are fetched on demand via message_index, unresolvable rows are skipped, and redaction behavior includes masking as [REDACTED_<TYPE>] and returning a redactions dict. It also describes return structure, truncation, and error handling, offering deep insight into the tool's behavior beyond mere input/output.

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 well-structured with a summary sentence, followed by detailed argument explanations and a clear Returns section. While somewhat long, every sentence provides essential information, and the front-loaded first sentence gives the core purpose immediately. It avoids fluff and earns its length.

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's complexity and the absence of annotations, the description covers all necessary aspects: input requirements, processing behavior, output shape, edge cases (unresolvable rows, unsupported format), and constraints (size-bounded, truncated_fields). It also references session_diff for known caveats, making it complete for an agent to use correctly.

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?

The schema provides only titles with no descriptions (0% coverage), but the description explains each parameter in detail: rows must contain id and refs with a file entry, per_file is the only mode, format supports only 'unified', and redact controls secret masking. This fully compensates for the schema's lack of documentation.

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 opens with a specific verb and resource: 'Stitch edit rows into a per-file chronological diff — the diff verb.' It clearly distinguishes from session_diff by explaining that it reproduces the synthesis from provided edit-event rows rather than querying directly. The purpose is unambiguous and aligns with the tool name.

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?

It provides clear context: use this when you have edit-event rows from a query and want a per-file diff, as opposed to session_diff which likely queries the session directly. It also notes that per_file and format are the only modes today, implying no alternatives within the tool. However, it does not explicitly list alternative tools or state when not to use it, though the contrast with session_diff gives implicit guidance.

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?

With no annotations provided, the description carries the full burden and does so impressively. It discloses redaction behavior, reference-by-default semantics, size-bounded output with truncation markers, the default 7-day time window, and the error contract translation—far exceeding minimal disclosure expectations and providing rich behavioral context.

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 long but every sentence earns its place, organized by labeled behavioral aspects (redact, reference, truncation, default window, wrapper). It is front-loaded with the core purpose and uses bolded inline terms to make scanning easy.

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's complexity and the presence of an output schema, the description covers all major behavioral areas: redaction, reference-by-default, truncation, default time window, and error mapping. It leaves no significant gap for an agent to misuse the tool, and the output schema handles return-value details.

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 compensate, and it explains redact, include_input, since/until, agent, and the distinction between output_truncated and count-based truncation. However, the 'limit' parameter is not explicitly tied to record-count behavior; while 'count-based truncated' hints at it, the direct semantic of limit remains implicit rather than stated.

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 opening sentence, 'Find every file edit across sessions, cross-agent by default,' uses a specific verb ('Find') and resource ('file edit across sessions'), and the phrase 'cross-agent by default' immediately distinguishes it from sibling tools like find_tool_calls or session_diff. It is immediately clear what the tool does and how it is scoped.

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 to fetch bodies on demand via get_body/read_session and when to pass include_input=True, giving practical alternatives. However, it does not explicitly state when not to use find_file_edits versus other sibling tools, relying more on implicit context than direct exclusions.

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?

Despite no annotations, the description discloses extensive behavioral traits: redaction masking with [REDACTED_<TYPE>] placeholders, filters matching raw pre-redaction text, tri-state is_error semantics, output_mode adaptive behavior, wrapper-aware classification, and honest subagent cost fallback gaps. This far exceeds typical transparency and fully describes edge cases without contradicting any structured metadata.

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 long but each paragraph addresses a coherent behavioral aspect, and technical details are interwoven with usage rationale. It front-loads the core purpose and then organizes by parameter and edge case, making it navigable. Some length is justified given the tool's 14-parameter complexity, though a few sentences could be tightened.

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 description is self-contained, covering error translation, subagent cost join mechanics, fallback behaviors, and the presence of an output schema. It answers 'what happens if' for background spawns, corrupted metadata, and multi-result records. This goes beyond a typical tool description and fully prepares an agent to use the tool correctly.

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%, and the description adds deep meaning to most parameters: redact, session, tool_name/tool_name_pattern, input_contains/output_contains/output_excludes, is_error, output_mode, and with_subagent_cost. It even explains session semantics relative to since/until and hints at agent scope with 'cross-agent by default'. While 'limit' and 'agent' are not explicitly detailed, the description compensates overwhelmingly for the schema's silence.

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 opening sentence uses a specific verb 'Find' and resource 'every tool call across sessions, cross-agent by default', clearly establishing the tool's scope. It distinguishes itself from siblings by focusing on tool calls and cross-agent scanning, which is not obvious from navigation-based tools like read_session or search_sessions.

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 clear when-to-use context, such as pinning the session when auditing one conversation and opting into with_subagent_cost for subagent billing recovery. It does not explicitly name alternative tools or state when not to use this tool, but the context and filters give strong practical guidance.

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?

With no annotations provided, the description carries full behavioral disclosure. It covers return format, truncation behavior with markers, redaction semantics and defaults, the fail-soft behavior of include_thinking, and error responses—all beyond what annotations would typically convey.

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?

Though long, the description is densely informative and well-structured: main purpose first, then parameter explanations, then return behavior. Every sentence adds operational value, and the examples (S6 case, fail-soft) clarify edge cases without redundancy.

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 5 parameters, a complex combination of behaviors, and no annotations. The description covers all parameter semantics, edge cases, defaults, and error handling. The presence of an output schema means return-value details are not required, but the description still states the return shape, making it complete for an agent to invoke correctly.

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?

The schema has 0% description coverage, so the description must explain all parameters. It does so thoroughly: id type and meaning, shallow's draft-skipping behavior, max_chars truncation with 0 to disable, redact's masking behavior, and include_thinking's conditional field. This fully compensates for the absent schema descriptions.

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 uses a specific verb ('Return') and identifies the exact resource ('on-demand body for an event / plan id'). It distinguishes between plan_event and user_turn/assistant_turn id types, making the tool's scope clear and differentiating it from sibling tools that handle sessions or audits.

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 explains when to use the tool (for on-demand body retrieval, deliberately off the event stream) and provides detailed guidance on which id types apply. It does not explicitly name alternatives among sibling tools, but the contextual cues ('bodies are deliberately kept off the event stream') imply when this tool is appropriate.

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?

With no annotations, the description carries full burden, and it delivers: discloses deterministic dictionaries (no LLM), false-positive potential (echo "rm -rf /"), redaction behavior, is_error null when no correlated outcome, count/truncated semantics, diagnostics on empty results, and the error contract. This is exemplary transparency.

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 long but dense and front-loaded with the purpose in the first sentence. It is organized into logical paragraphs (purpose/mechanism, filters, output, caveats, wrapper). A 5 would require tighter structure (e.g., bullets), but every sentence earns its place.

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 11 parameters, no annotations, and no schema descriptions, the description is remarkably complete. It covers output fields (id, patterns, categories, command fragment, is_error, confirmed, reaction, count, confirmed_count, by_pattern, truncated, diagnostics), cross-references to query/read_session, and error handling. Nothing critical 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 0%, but the description compensates by explaining every parameter with semantics: filters (agent, session, since/until, category, confirmed, noise, project_dir), limit default/cap, redact masking, reaction_window default, and category 'unknown values fail loud'. This fully covers all 11 parameters.

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 opens with 'Dangerous shell commands + regret reactions' and states the one-call question: 'where did an agent run something destructive — and did it then apologise?'. This is a specific verb+resource scope and clearly distinguishes it from raw query or tool-call siblings by framing it as a preset over the core.

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?

Clear context is provided: 'One call answers...' and the internal mechanism (one query scan, dictionaries, reaction_window) helps the agent decide when to use it. However, it does not explicitly state when not to use it or name alternative sibling tools, so it falls short of a 5.

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?

No annotations are provided, so the description carries full responsibility. It is exceptionally transparent: explains sorting and pagination, subagent detection per source, origin field mappings, recency semantics with clock-skew handling, redaction behavior, and the 'honest contract' warning about liveness. This goes far beyond basic expectations and discloses caveats clearly.

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?

Though the description is long, it is densely informative. It front-loads the core purpose, then systematically details behavior, parameters, and return contract. Each section adds value; there is no filler or tautology. The structure with Args/Returns mirrors schema for easy scanning.

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 description is complete for a tool of this complexity. It covers all 7 parameters, return fields with edge cases (truncated, diagnostics), cross-source format differences, and even the liveness caveat. The existing output schema is enriched with semantic explanations, and the description leaves no critical gap.

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?

Input schema has 0% description coverage, but the description compensates fully. Every parameter is explained with semantic detail: agent values, limit=0 meaning no cap, offset pagination, kind/noise composition, project_dir path-boundary awareness, and redaction behavior. This adds significant meaning beyond the bare schema 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?

The description opens with a specific verb+resource combination: "List discoverable sessions, optionally filtered by agent." It clearly identifies the tool's scope (listing discoverable sessions) and differentiates from siblings by emphasizing enumeration and discoverability rather than search or detailed read operations.

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 clear context for how to use the tool (filters, pagination, defaults) but does not explicitly name alternatives or state when not to use it. Sibling tools like search_sessions exist, but the description never contrasts this listing tool against them. Use-cases are implied rather than explicit.

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?

With no annotations, the description carries the full transparency burden and exceeds expectations. It discloses the deterministic matching algorithm, ranking by last activity, the exact match fields (path, agent, project_dir, date, size_bytes), the honest 'readable' flag, the non-executed resume_command, limit/count/truncated behavior, zero-match suggestions instead of fabricated results, web=true's "honest scope", and the ValueError-to-error mapping.

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 long but every sentence adds value: algorithm, result fields, command generation, limit semantics, empty-result behavior, web scope, and error mapping. It is front-loaded with the core purpose and then systematically expands into necessary edge-case detail without fluff.

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 5-parameter tool with no annotations and no schema descriptions, the description is remarkably complete. It covers search semantics, result structure, command generation, output limiting, zero-match handling, web mode limitations, and exception mapping. The only minor omission is the semantics of 'agent' and 'redact', but the overall context is sufficient for correct invocation.

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 0%, but the description richly explains needle (full uuid, id-prefix, case-insensitive title substring), limit (0 = no cap, count/truncated flags), and web (local-only known entries, hook files, teleport stubs with content_local). However, 'agent' and 'redact' parameters are not explained anywhere, leaving a clear gap despite the otherwise strong compensation.

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 opening line states the tool's exact purpose: "Find a session across all agents by uuid / id-prefix / title". It distinguishes itself from siblings like list_sessions and read_session by promising to answer where a session lives and how to read it, while returning ready-to-run commands.

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 frames the core use case: "I remember a session — where does it live and how do I read it?". It explicitly positions the tool as a preset over the existing list_sessions walk and clarifies current limitations (e.g., the fuller teleport-picker sweep requires a PTY and is a documented follow-up), providing clear when-to-use and scope boundaries.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It exhaustively details the deterministic risk dictionary, the zero-LLM/zero-guessing policy, the handling of missing targets (null fields), risk firing only on parse/regex evidence, the redact behavior, limit bounds with truncated flag, tri-state is_error semantics, and the error contract mapping. Honesty caveats are explicitly documented, such as risk labels not being a threat oracle.

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 long but every sentence earns its place for an 11-parameter audit tool. It is front-loaded with a clear one-sentence summary, then structured into how it works, filters, output, and honesty caveats. No filler or redundancy.

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's complexity (11 parameters, 0% schema description coverage, no annotations) and the presence of an output schema, the description is remarkably complete. It covers the full output shape (count, risky_count, by_domain, by_risk, truncated, diagnostics), edge cases (empty results, missing targets), and error handling. An agent has everything needed to select and invoke the tool correctly.

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 0%, but the description adds meaningful semantics for every parameter: agent, session (uuid or list), since/until (ISO bounds on call ts), kind (fetch|search with fail-loud on unknown values), risk (include only/exclude), domain (equals-or-subdomain match), noise and project_dir (session-level semantics), limit (default 50, 0 = no cap), and redact. This goes far beyond the raw schema types and defaults.

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 states the tool performs a Network-egress audit, answering 'where did an agent reach out to the network — and how risky did those requests look?'. It distinguishes itself from siblings by explaining it is a preset over the existing core (not a second engine) and focuses specifically on web tool calls (WebFetch, WebSearch, webfetch, web_search, etc.).

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?

Provides explicit when-to-use context: one call answers network egress and risk. It also gives clear when-not-to-use guidance, noting MCP-mediated network access stays under tool_kind='mcp' and is never guessed into this audit, and that Pi records no web tool (honest absence). It references query/read_session for walking context, effectively suggesting alternatives for further investigation.

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?

With no annotations, the description fully discloses behavioral traits: normalization of signals from different agents, grouping logic, versioning, redaction defaults, filtering of technical failures, and the precise semantics of feedback anchors ('never a nearest guess'). It also explains what output to expect and how parameters change 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?

The description is long but exceptionally well-structured: an introductory summary, followed by detailed schema explanations, then parameter and return specifications. Every sentence adds substantive information, and the structure makes it easy to navigate. It is front-loaded with the core purpose.

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 tool with 8 parameters, an output schema, and complex normalization logic, the description is exhaustive. It covers all input options, output structure, edge cases, and internal behaviors, leaving no ambiguity. The presence of an output schema doesn't reduce the need for this detail, and the description provides it.

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 0%, so the description carries the full burden. The 'Args' section explains every parameter (session, kind, group, agent, redact, bodies, feedback, rounds) with defaults, allowed values, and behavioral effects, fully compensating for the bare 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 function: 'Normalized plan atoms for a session — final vs drafts, grouped by task.' It clearly identifies the resource (plan events) and the action (normalization), and distinguishes itself from siblings like get_body (draft bodies on demand) and query (the underlying raw call).

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 explicitly states when to use it (to get normalized plan data grouped by task) and references alternatives: it 'wraps query(type=...)' and notes that 'Draft bodies and raw responses stay on-demand via get_body.' It also provides parameter-level guidance (e.g., 'session: Restrict to one session uuid (recommended)') and explains the behavior of edge cases like 'rounds' failing loud.

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?

With no annotations, the description carries the full burden and excels: it discloses fail-loud invalid_argument cases, relative_to ignoring other facets, emission-time redaction, ~160-char preview truncation, semantic search degradation with fallback, and diagnostics on empty results. This level of edge-case disclosure is exceptional.

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 well-structured with bold facet names and a front-loaded purpose, but it is verbose and repeats phrases like 'honest empty result' and 'Ignored on the relative_to walk, like every other filter facet' multiple times. The length is mostly justified by 25 parameters and zero schema descriptions, but tighter editing would improve it.

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's high complexity, no annotations, and zero schema descriptions, this description is remarkably complete. It covers all parameters, return shapes, error behavior, redaction, truncation, filtering precedence, and corner cases, leaving little to guess.

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 0%, and the description fully compensates by explaining every facet: type values, session union semantics, tool/tool_kind/tool_resolved matching, model inheritance, user_ref special values, has_thinking gating, sort modes, relative_to walk, noise/project_dir/parent filters, group, redact, and the kind tombstone. It adds far more meaning than the sparse schema provides.

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 opens with a specific verb+resource: 'Filter/search the unified session **event** stream', and immediately clarifies the normalized event types. It differentiates from siblings by positioning itself as the event-stream workhorse and referencing related tools like search_sessions and find_file_edits, making the scope clear.

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?

It provides clear context: this is the primary tool for filtering/searching the unified event stream, 'all behaviour is parameters, never hard-wired variants', and it mentions related tools like search_sessions and find_file_edits for shared concepts. However, it never explicitly states when to use this tool versus a sibling, nor lists exclusions or alternatives, so it stops short of a 5.

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?

With no annotations provided, the description carries the full burden and excels. It discloses the matching mechanism (normalization + SequenceMatcher), the honest null for runs below minimum, the no-fabrication guarantee, normalization caveats (markdown stripped, not byte-identical), redact behavior, limit/truncation semantics, and diagnostics on empty results.

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?

Though lengthy, the description is front-loaded with the core purpose and every sentence adds essential operational detail. It is well-structured into focused paragraphs covering filters, output records, caveats, and error contract—no filler or redundancy.

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's complexity (9 params, no annotations, rich output schema), the description is remarkably complete. It documents all filters, result fields, output behaviors (count, limit, truncated), edge cases (count == 0 diagnostics), and the error translation to invalid_argument, leaving no major usage gap.

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 0%, so the description must fully compensate, and it does. Every parameter is explained with syntax and semantics: session accepts uuid or list, since/until are ISO bounds on user turn timestamp, noise and project_dir mirror query, source_kind values fail loud, limit default 50 with 0 meaning no cap, and redact defaults to true masking secrets.

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 opens with a specific verb+resource statement: 'User quotes of prior in-session content' and immediately answers the exact question the tool resolves. It explicitly distinguishes itself from sibling tools like plan(feedback), emphasizing it is the cross-agent generalization covering 'any prior message quote → user comment.'

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 direct when-to-use guidance: 'One call answers "where did the user quote something the agent said..."' and contrasts it with plan(feedback), which only covers Claude's plan-approval flow. It also gives clear parameter-driven usage context, such as source_kind currently only supporting assistant prose and failing loud on unknown values.

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?

No annotations are present, so the description fully documents behavior. It covers pagination, redaction, token estimation, subagent rollup, thinking inclusion, and edge cases such as ambiguous ids returning candidates and missing sessions returning an error dict. This is transparent, honest disclosure of side effects and return shapes.

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 text is lengthy but structured: a one-line summary, then Args, Returns, and edge cases. Each section is purposeful, though some explanations (e.g., the detailed token source ladder) could be condensed without losing essential meaning.

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's complexity (8 parameters, no annotations, rich return structure), the description covers every parameter, details all return fields, and handles edge cases. It is a self-contained reference for correct invocation.

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?

With an input schema that has 0% description coverage, this description thoroughly explains each parameter: uuid, agent, offset, limit, redact, with_tokens, include_subagents, include_thinking, including defaults and interactions. It fully compensates for the schema's lack of detail.

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 opens with 'Read a single session by uuid', a specific verb and resource. It clearly differentiates from siblings like list_sessions and search_sessions by focusing on a single session identifier.

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?

Clear context is provided: use this tool with a known uuid, and optionally disambiguate with agent. The description explains what happens when agent is omitted and how to handle collisions. It does not explicitly mention alternative tools, so it stops short of a 5.

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?

With no annotations, the description fully carries the transparency burden and does so excellently. It discloses case-insensitivity, search operators, negative-prefix behavior, noise filter semantics, redaction that still allows raw matching, include_thinking budget implications, caching behavior, and honest degradation for semantic sort. It even documents error return format. Exceptionally transparent.

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 long, but it's a complex tool with 9 parameters and subtle behaviors. It is well-structured: opening line, Args block, Returns block, Errors note. Every sentence adds necessary detail; no filler. Slightly verbose for a quick read, but appropriate given the tool's complexity, so not a 5.

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 description is complete for a complex search tool. It defines the result dict, count, snippet field, body_truncated, diagnostics on empty results, and the semantic report. It covers edge cases, fallback behavior, and error convention. No critical behavioral aspect is left unexplained. Given the tool's complexity, this is fully complete.

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 has 0% description coverage, and the description thoroughly compensates. Every one of the 9 parameters is explained beyond type alone: query supports special syntax (quoted phrases, negative prefix), scope enumerates options with examples, operator explains AND/OR/NOT and negative-term interplay, limit describes post-sort application, sort details BM25 vs date vs semantic with fallback, noise defines 'noise' precisely, redact explains masking and raw-search behavior, include_thinking covers haystack modes and caching. This is exemplary parameter documentation.

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?

Opening line is clear: 'Case-insensitive search across sessions.' Specific verb+resource. Does not explicitly differentiate from siblings like list_sessions or query, but the search semantics are apparent. Loses one point for not naming alternatives, but purpose itself is unambiguous.

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 guidance on when to use this tool vs siblings. Does not mention list_sessions, query, find_tool_calls, etc., or provide any exclusionary context. The detailed Args section explains how to configure the search, but not when the tool should be preferred. Thus, only implied usage, no explicit decision framework.

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?

With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly states two blind spots (actions vs. git outcome, and shell-redirect gap vulnerability), describes redaction behavior with redact=True/False, explains truncation and byte budgets (output_truncated, truncated_fields), and details error-shape translation. This is exceptionally transparent for a tool with zero annotations.

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 front-loaded with the core purpose and clearly structured across paragraphs. It contains a moderate amount of detail—caveats, redaction, truncation, error handling—but every sentence contributes useful information. It is not overly terse nor bloated, though it is longer than strictly necessary.

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?

Despite an output schema being present, the description goes beyond and explains the return shape, caveats, truncation, redaction, and error handling. It is comprehensive for a complex tool. The only notable omission is the meaning of 'path', but the overall context and references to sibling tools make the tool's behavior clear enough for selection.

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 0%, so the description must compensate for all four parameters. It only explicitly explains redact (default true, masks secrets). session_uuid and agent are inferable from names but not described, and path is not addressed at all despite being an optional parameter. The description does not provide semantics for a quarter of the parameters, leaving a significant gap.

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 opens with a specific verb+resource+scope: 'Reconstruct *what the agent changed* in one session — without git.' It clearly differentiates from siblings by mentioning find_file_edits, get_body, and read_session, and by emphasizing it builds a per-file chronological diff from edit records, not a git diff.

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 clear context for when this tool is appropriate: when you need a diff of the agent's actions without git, and it explicitly warns that manual edits, partial commits, and merges are invisible. It names alternatives for getting full edit bodies (get_body/read_session) and references find_file_edits for shell-redirect gaps, but it does not explicitly say 'use this instead of X' in a comparative form.

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?

With no annotations, the description carries full burden and does so thoroughly. It discloses that with_tokens reads at request time (nothing in background), explains exact vs estimate vs unknown token accounting, states that sums with no data stay null (never fabricated), notes the redaction-safe nature, and details the scan guard's error/return behavior. This is exemplary transparency.

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 long but every paragraph earns its place: purpose, grouping options, token behavior, scan guard, and error mapping. It is well-structured with clear headers (RISK-4 note, group_by enumeration) and uses examples. No redundancy or 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 an 8-parameter tool with no annotations and 0% schema description coverage, this description is exceptionally complete. It explains the output group fields (edits, intents, agents, messages), token block contents, totals behavior, error shapes, and the exact wrapper contract. The existing output schema plus this description leaves a well-rounded picture.

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 compensate. It thoroughly documents group_by (all five enum values with nuances like '(mixed)' and '(unknown)'), with_tokens (including sub-fields and exact/estimate/unknown semantics), and token_scan_limit (including 0 disables cap). However, top and edit_path are not explicitly explained, though their meanings are partially inferable. The gap prevents a 5 but is still strong overall.

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 opens with 'Summarise sessions, grouped and ranked — the bird's-eye audit view,' which uses a specific verb and resource. It explicitly contrasts with siblings (find_file_edits / find_tool_calls return flat record streams) and explains the grouping/rollup distinction, so it clearly differentiates from alternatives.

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?

It provides explicit when-to-use guidance: 'Where find_file_edits / find_tool_calls return flat record streams, this rolls the sessions themselves up by one dimension.' It also gives actionable tips (e.g., 'Pair with with_tokens=True to see what each model actually cost') and warns about the scan guard, including when to narrow scope or raise token_scan_limit.

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