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

With no annotations, the description carries the full load and does most of it: paging contract (start/end exclusive, next_start, max_chars budget, truncated oversized turns), caveats that files_touched appears only on the first part with a 200-path cap, sub-agent listing limits, parent_session_id, and the staleness warning that these are dated records rather than live PR/issue state. What it never says explicitly is the safety profile (that this is a non-mutating read with no auth/permission requirements), so a 4 rather than a 5.

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?

Information-dense but structurally heavy: one enormous run-on sentence packs the turn-window, paging, files_touched caps, sub_agents and parent_session_id together, and the aside "Whole-session paging below is the fallback" refers to text that arrives later. Nearly every clause is load-bearing, but sectioning or bullets would make the branching logic far easier to scan.

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 five-parameter paginated reader with no output schema and no annotations, the description still tells the agent what comes back (session metadata, summary, turns, files_touched, sub_agents, returned/next_start), how to continue, and when the data is stale. There is no output schema to lean on, and the return shape is nonetheless fully described.

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 100%, so the baseline is 3; the description earns extra credit by explaining interactions the schema only hints at, such as turn winning over start, the ±window focus object returned ({turn, window, first_idx, last_idx, total_turns}), and that max_chars defaults to 12000 in turn-mode versus 60000 otherwise. Much of the per-parameter default/clamp text duplicates the schema, which keeps it from a 5.

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?

Opens with a specific verb and resource ("Retrieve a specific coding session by ID") and immediately enumerates the payload: user-spine turns, files touched, per-session summary. It also explicitly contrasts itself with the sibling session_summary ("short threaded overview of the same session") and ties its ID to memory_search records and list_recent_conversations rows, so an agent can place it among siblings without reading any 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 concrete entry paths (a memory_search record's session_id + turn_idx, a list_recent_conversations code row's id) and states the selection rule against the alternative: "Use it to read what was actually said; use session_summary for a short threaded overview." It also documents the drill-down loop (repeat with start=next_start until next_start is null) and the sub-agent traversal, leaving little 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?

With no annotations present, the description carries the full burden and does well: it discloses part-based pagination, the default budget (~60000 chars), the returned metadata fields, and that tool calls/results are stubbed by default to protect the budget. It does not cover error behavior for an invalid id or any access/permission constraints, which keeps it from a 5.

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?

Front-loads the core purpose, then the pagination contract, then the tool-IO caveat. Dense but every sentence conveys behavior an agent needs; the trailing tool-IO sentence partially duplicates the schema's include_tool_io description, costing a point.

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?

There is no output schema, so the description must describe return shape — and it does, naming total_messages, total_chars, returned {start, end (exclusive)} and next_start, plus truncation of oversized single messages. An agent has everything needed to page through a conversation to completion.

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 100%, so baseline is 3; the description earns above that by explaining the continuation protocol that binds `start` to `next_start` and by giving the rationale for `include_tool_io` (tool payloads are enormous and blow the part budget). It still defers the actual bounds and clamping to the 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?

States a specific verb and resource ('Retrieve a specific conversation by ID with its messages'), which cleanly separates it from list_recent_conversations and search_conversations that operate without an ID. It does not explicitly name a sibling to contrast with, so it stops short of a 5.

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 explicit operational guidance for the common multi-call case: when next_start is not null, call again with the same id and start=next_start until null. That is clear context for correct invocation, though it offers no routing advice about using search_conversations or list_recent_conversations to discover an id first.

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 exist, so the description carries full behavioral burden. It does disclose the returned payload (rollup summary, session count, last-active time), which is valuable given there is no output schema, but it says nothing about scoping restrictions, ordering, or pagination for a tool that could return many projects.

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 that identifies the resource, its scope, and the payload in one pass. Every clause ('coding-agent projects', 'repos worked on via Claude Code') earns its place by disambiguating what a project is.

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 no output schema, the description usefully enumerates what the results contain, which is the main thing an agent needs to decide to call it. Given zero parameters and a simple read listing, little else is required; only result ordering/volume behavior is left unstated.

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 tool takes zero parameters and the schema is empty, so there is nothing to document; baseline 4 applies. The description correctly adds no spurious parameter guidance.

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 (List) and resource (the user's coding-agent projects), with a parenthetical scoping clarification ('repos worked on via Claude Code etc.'). This clearly separates it from get_code_session, which retrieves one session rather than a project rollup, though no sibling is named.

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?

Usage is only implied — an agent can infer this is the entry point for project discovery versus get_code_session for drilling into a session. There is no explicit when-to-use / when-not-to-use statement or named alternative.

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 does so: defaults (last 7 days, both kinds), metadata-only return, per-type field lists including the 200-char summary cap, and that downstream get_* tools return long results in parts. It also warns results are dated records rather than live PR/issue state, which is exactly the kind of caveat annotations would otherwise supply.

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?

Front-loaded with purpose and scope, and essentially every clause carries information (row shapes, defaults, routing, caveat). It is a single dense paragraph with heavy parenthetical stacking, which costs a little readability but no sentence is 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?

Five optional parameters, no annotations and no output schema — the description covers what is returned for both row types, the defaults, pagination-adjacent limit behavior implicitly, and the caveat about staleness. Nothing an agent needs to call this 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 coverage is 100%, so the baseline is 3; the description still adds value by restating the temporal defaults and by showing how natural-language intents map to parameter values (since for 'yesterday', kind for chat-vs-code). It doesn't add syntax beyond the schema's ISO examples.

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 (List) and resource (recent sessions) and immediately disambiguates scope: chats AND coding sessions, main sessions not sub-agents, newest first, metadata only. It even enumerates the row shapes per type, so an agent can distinguish it from search_conversations or session_summary 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?

Explicit when-to-use with a concrete worked example ('yesterday's chat → since = yesterday's date, kind = chat') and explicit follow-up routing to get_conversation / get_code_session. It does not name the alternative for content-based lookup (search_conversations), so the exclusion side is only implied.

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 does: it discloses result ordering (kind-priority then recency), dedup semantics (replaced records hidden, paraphrases served once with seen_in), the as_of timestamp on every record, and an explicit caveat that links locate sources rather than report current state. That is unusually rich behavioral context for a read tool.

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?

Purpose and the memory_search exclusion are front-loaded in the first clause, and every subsequent sentence carries new information. The style is telegraphic (fragments like 'Ordered kind-priority then recency', em-dash asides), which is efficient but slightly dense to parse on first 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?

Covers return shape (links, seen_in, as_of, hidden replaced records), result ordering, and follow-up navigation, which is a lot for a tool with no output schema and no annotations. It does not mention pagination or whether truncated result sets are signaled, a minor gap for a 7-parameter read tool.

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 100%, so baseline is 3; the description still adds meaning by showing that kind='outcome' alone is a valid, useful call shape and by framing path/repo as the primary selectors. It does not add anything for scope, durable_only, or recall_token beyond the schema, so it is an incremental gain rather than full 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?

States a specific verb (recall) and resource (memory records) and immediately bounds the scope: by repo or path, not by topic. It names the sibling memory_search as the tool for the excluded case, so an agent can pick between them without opening either 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?

Explicit routing to memory_search for topic lookups and to get_code_session for surrounding turns, plus a concrete usage hint ('outcome' alone answers 'what shipped here lately'). It does not address when to prefer memory_resolve or the list_* siblings, so the alternative coverage is partial rather than complete.

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 does so: it discloses the blast radius ('the blocker and its repeats are closed for every later session'), reversibility ('the owner can restore it'), and a validation mechanism ('the quote is checked against this session's transcript when it uploads'). It also pre-empts a likely failure mode by forbidding tool output as the quote source.

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?

Front-loaded with the action, then timing, then consequences, then the permission constraint — a sensible order with no filler sentences. Slightly dense with nested parentheticals ('in the preamble, memory_search or memory_recall', 'not tool output, which is not stored'), which marginally slows 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?

For a mutation tool with no annotations and no output schema, the definition covers when to call, what it affects, how the quote is validated, and who may call it. The remaining gap is what happens on rejection (e.g. a quote that fails transcript validation) and what the call returns, though the latter is a minor omission for a simple state-change.

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 100%, so parameter definitions alone would justify a 3. The description adds meaning beyond the schema by explaining why the quote must be verbatim message text — it is re-validated against the uploaded transcript and stored as the receipt — which gives the agent a reason to comply rather than just a rule.

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 ('Mark a blocker as fixed') and immediately anchors it to the blocker objects surfaced by the sibling tools memory_search and memory_recall. An agent can tell this apart from the read-only search/recall siblings without opening any 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 explicit timing ('Call this right after you fix a blocker') and names the upstream sources that produce the blocker (preamble, memory_search, memory_recall). It also states an exclusion — 'Only your own open blockers can be resolved' — which prevents misuse on other users' or already-closed records.

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 exist, so the description carries the full burden, and it delivers: ranking rules (newer wins ties), date-hint soft ranking vs since/days hard filtering, superseded-record hiding and how to unhide, paraphrase merging with seen_in, as_of staleness, extraction coverage window (~30 days of upload), and two different result-shaping modes (served vs records with raw_reason/dropped_for_budget). It also states that an empty result with a 'reason' is a valid answer, not an error.

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?

Purpose is front-loaded in sentence one, but the body is a dense run-on with repeated content: since/days filtering is explained twice and the 'records are not current state' caveat is stated twice ('they do not report current state' and 'not the current state of a PR or issue'). The information is valuable but could be tightened without loss.

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 11-parameter tool with no output schema and no annotations, the description covers return shapes, key fields (date_hint, seen_in, as_of, dropped_for_budget, served), failure semantics, and source-link fields (sha, paths, ref_url). An agent has what it needs to call and interpret results.

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 100%, so baseline is 3; the description goes beyond it by clarifying that since/days filter on session start time while each record's `when` is session end time, and by explaining that include_superseded is implicitly true when the query names a past date. Remaining params (kind values, limit, project, recall_token) are left to the 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?

First sentence states a specific verb and resource ('Search past sessions' learnings, decisions, blockers...') plus the search mode (full-text fused with semantic) and the agent-facing intent ('what did we decide/learn about X'). It explicitly marks its boundary against search_conversations for unextracted facts, so an agent can choose without opening schemas.

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 conditions: use this for topics, use search_conversations for raw turns, and follow up with get_code_session/session_summary when you need surrounding context. It does not differentiate itself from memory_recall or memory_resolve, so the sibling routing is incomplete, but the affirmative usage context is strong.

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 does so: it discloses that hits are raw text 'as said, not extracted, checked or versioned', that they are dated records rather than current state ('check that live'), and that chunks resolve to message spans. These are non-obvious semantic traits an agent could not infer from the schema alone.

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?

Dense but front-loaded: purpose first, then time-filter usage, then the sibling routing, then the truth-vs-record caveats. Each sentence addresses a distinct concern, though the closing three caveat clauses stack up and 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?

For a 5-parameter search tool with no annotations and no output schema, the description covers invocation, alternatives, time filtering, and return-value semantics. An agent has everything needed to call it correctly and interpret hits.

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 100%, so a baseline of 3 applies, but the description adds real value by explaining when to prefer since over days and giving a natural-language example of mapping a relative date to since. The scope parameter is not addressed in the description, keeping it below a 5.

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 dual resource ('Search the user's synced conversations AND coding-agent sessions') plus the retrieval modes (keyword and semantic similarity). It also pins down result shape (source_type tagging, resolution to message span rather than title), which lets an agent distinguish it from get_conversation and list_recent_conversations 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?

Explicit routing to alternatives: browsing with no query goes to list_recent_conversations, and decisions/learnings/outcomes go to memory_search. It also gives a concrete time-filter recipe ('yesterday's chat about X → query = X, since = yesterday's date'), leaving little 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?

With no annotations, the description carries the full burden and does well: it discloses ordering semantics (threads in order from the first prompt, records with outcomes first), scoping (files touched in that range), and the crucial data-freshness trait that results are historical records rather than live state. It stops short of covering result size, truncation, or cost of a call, so not a 5.

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?

Three sentences, front-loaded with purpose, then routing, then the freshness caveat; the parentheticals all carry information rather than filler. Nothing could be removed without losing selection-critical detail.

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-param read tool with no output schema, the description conveys the return shape well enough (header fields plus an ordered journey of threads and records) and flags the historical nature of the data. It leaves open the default selection behavior when no identifying parameter is given, and jargon like 'records'/'threads' is not defined, which is a modest remaining 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 100%, so `last`, `repo`, `session_id` (including the ≥8-char prefix rule) and `recall_token` are already fully documented in structured fields. The description adds nothing about parameters — notably it never explains selection precedence when neither `last` nor `session_id` is supplied — so 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 and resource ('Get one coding session's header ... and its JOURNEY') and enumerates the returned fields (repo, branch, turns, models, files touched, threads, records). It explicitly names the sibling get_code_session and the condition that selects it, so an agent can route without opening either 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 a positive selection rule ('short story of a session — what it set out to do and what it found'), names the alternative for a different need ('use get_code_session when you need the actual turns, e.g. the exact words around a memory_search record'), and warns when not to rely on it ('dated records ... not the current state of a PR or issue; check that live').

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