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

Since there are no annotations, the description carries the behavioral disclosure burden. It adds useful context: entries may be read back later without surrounding conversation, and pinned entries survive compaction. It does not cover output behavior or other side effects, but the key memory-semantics are disclosed.

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 four sentences with no filler. The core purpose is front-loaded, and each remaining sentence adds essential guidance about cadence, self-containment, and pinning.

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 tool with no output schema and no annotations, the description covers purpose, when to use it, and behavioral nuances. Minor missing context is explicit routing away from context_update, but the schema handles parameter details adequately.

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 adds value beyond the schema by explaining that text must stand alone and that pinned entries are protected from compaction, both of which clarify how to use the corresponding 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 a specific action and resource: 'Record something worth remembering into the session.' It clearly communicates an append/write behavior and is readily distinguishable from sibling tools like context_recall, context_compact, and context_update.

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 gives concrete triggers for use — 'after discovering a fact, making a decision, or hitting a dead end' — and explains the intent of recording incrementally. However, it does not explicitly state when not to use this tool or name the alternative for updating existing entries, such as context_update.

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 covers key traits: pinned entries are never compacted, originals are kept on disk and recoverable, and dry_run is recommended for previewing. These are non-obvious behavioral details that an agent needs to know before calling, and they are clearly stated. The safety/reversibility disclosure is particularly strong.

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 four sentences, all essential. It front-loads the core action, then the trigger, then safety, then a recommendation. There is zero fluff; every sentence earns its place. It is compact and efficient, matching the tool's own 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?

Given the tool's complexity (4 params, 1 required, no output schema) and the rich schema descriptions, the description is nearly complete. It covers when to use, what it does, safety, and workflow advice. The only minor gap is that it doesn't mention error conditions or the exact nature of the summary, but those are not critical for an agent to call it correctly. The description complements the schema well, earning a 4.

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 per the rubric. The description adds some contextual meaning (e.g., 'keeping the most recent entries verbatim' hints at keep_recent), but it does not elaborately explain each parameter beyond what the schema already documents. The schema descriptions for each parameter are thorough, so the description's additional value is marginal but present. This aligns with the baseline for high coverage.

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 precise verb and object: 'Fold older entries into a single summary to free budget.' It immediately distinguishes the tool from siblings by specifying the compaction behavior and the criteria for what stays verbatim. This is highly specific and leaves no ambiguity about the tool's function.

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 the trigger: 'Call this when context_status or context_append warns that the session is over budget.' It also advises using dry_run first. This gives an agent a clear, actionable condition for when to invoke the tool, and provides a safety step. No alternatives are listed, but the trigger is so specific that it satisfies the dimension.

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 at least implicitly acknowledges it's a read-only introductory aid, but does not detail output format or what happens if called repeatedly. Some prior exposure to the tool family or server is needed to appreciate its purpose.

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 short and direct, delivering both purpose and when-to-use in two sentences, front-loading the core message without extra bulk.

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 zero-parameter tool, the description covers purpose and usage. It doesn't mention any potential side effects or the exact content, but given the simplicity, it is largely 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?

The tool has zero parameters, and the schema provides high coverage (100%), so the baseline is high. The description appropriately focuses on the tool's behavior rather than parameter details, which are irrelevant here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool explains how to use the server and the intended workflow, combining guidance with a recommendation to call it once for new users. It distinguishes itself from siblings by being meta-guidance about the tool family, not a specific operation.

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 tool explicitly tells the agent when to call it ('if you have not used these tools before') and its purpose in onboarding. It distinguishes from siblings because they perform specific operations, while this provides overarching usage 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?

There are no annotations, so the description carries the behavioral burden. It discloses that the tool lists stored sessions in newest-first order and implies a read-only operation. This is adequate for a simple, parameter-free listing tool, though it does not explicitly state side effects or return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no fluff. The first states the action and ordering, the second gives a practical use case. Every sentence contributes meaningful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool, the description covers everything an agent needs: what it lists, the ordering, and why to call it. Nothing essential is missing because there is no complex schema, security concern, or ambiguity requiring further disclosure.

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 exposes zero parameters, so there is no parameter-level ambiguity to resolve. The description does not need to add parameter meaning because there are none, earning the baseline score for a tool with no 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 clearly states the tool's action ('List stored sessions') and a distinguishing detail ('newest first'). It also names the concrete use case of finding a session id, making its purpose unambiguous and distinct from the doc_* siblings.

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 a specific scenario where the tool should be used: finding a session id from earlier work. It does not mention exclusions or alternatives, but the context is concrete enough for an agent to recognize when this listing 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 the full burden and does so well. It discloses that the tool both starts and resumes, that it returns previously stored content, and that resuming after a restart surfaces prior knowledge. These are non-obvious behavioral details beyond what the name or schema alone could 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?

Three sentences with no filler: the core action is front-loaded, followed by a concrete usage condition and a behavioral outcome. Every sentence contributes essential information an agent needs before calling the tool.

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 lacking an output schema and annotations, the description explains what the tool returns when resuming, when it should be called, and how to manage session_id. This is sufficient for an agent to select and invoke the tool correctly in a long-running task workflow.

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, but the description adds real operational meaning to session_id by stating it must be reused consistently across calls. It reinforces the schema's existing description without restating it verbatim, adding value for the agent's invocation strategy.

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 phrase, 'Start or resume a named memory session,' which precisely identifies the resource and action. This clearly distinguishes it from siblings like context_append, context_recall, and context_list_sessions without requiring the reader to infer meaning.

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 explicit when-to-use guidance: call once at the beginning of long-running tasks and reuse the same session_id for later calls. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to decide correctly.

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 behavioral burden. It discloses useful traits: results are 'packed to fit a token budget,' pinned entries are always included, and omitting the query switches to most-recent ordering. These go beyond the schema and help an agent predict 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?

Four sentences with no filler. The primary action is front-loaded, followed by usage context and two key behavioral caveats. 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?

For a 4-parameter tool with no annotations and no output schema, the description covers the main use case, query omission, pinned entries, and token budgeting. It does not specify the return shape or how limit and budget_tokens interact, but it is largely sufficient for an agent to 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 coverage is 100%, so the baseline is 3. The description adds value by clarifying query omission behavior ('Omit the query to get the most recent entries instead') and explaining the token-budget intent behind budget_tokens. It does not detail the interaction between limit and budget_tokens, but it compensates beyond 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?

The description opens with a specific verb and resource: 'Retrieve the most relevant stored entries for a query.' It also distinguishes itself from siblings by calling itself 'the main way to get memory back into your working context' and contrasting with 'reading the whole 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 clearly states when to use the tool: when you need memory back into context, ask for what you need rather than reading the whole session. It also explains the no-query variant for recent entries. However, it does not explicitly name alternatives or state when not to use this tool versus siblings like context_open or doc_search.

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 must carry behavioral disclosure. It does mention the tool is cheap to call contaminating performance traits)Skip it also lists what it reports (fullness, pinned items, compaction advice). However, it does not explicitly state that it is a read-only operation with no side effects, nor does it mention any error conditions or output format. For a read-only status tool, the read-only nature is implied but not stated, and that is an omission given the description carries the full burden without 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?

Two sentences, no filler. The first sentence states exactly what the tool reports (fullness, pinned items, compaction advice) and the second provides the usage context. Front-loaded and every word 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?

The description clearly covers what the tool reportsheb, when to use it, and that it is cheap. Since no output schema is defined, the description compensates by listing the key diagnostic outputs. The only minor gap is precisely how the response is structured (e.g., numeric vs. textual), but for a status/decision support tool, this is sufficient.

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 single parameter session_id is fully described in the schema (100% coverage) with a clear explanation about reusing the same ID for memory accumulation. The tool description itself does not add specific details about the parameter beyond what the schema already provides, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports session fullness, pinned items, and compaction advisability. It names a specific verb ('report') and resource (session status), and distinguishes it from siblings like context_compact and context_append by focusing on status inspection rather than mutation.

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?

Explicitly tells the agent when to call it ('use it to decide whether you need to compact before adding more') and characterizes the call as cheap, signaling it's a low-cost diagnostic step. This is clear guidance with a specific decision context, making alternatives obvious.

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 available, the description carries the burden of disclosure. It explicitly mentions that pinning affects compaction survival and that deletion removes from recall, which are non-obvious behavioral consequences. It does not specify edge cases like simultaneous pin+delete, but this is acceptable for a simple mutation 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?

Two sentences with zero wasted words. The action verb and primary resource are front-loaded, and the purpose/effect follows immediately. It is perfectly sized for quick comprehension.

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 two required and two optional booleans, the description adequately covers what the tool does and why. It doesn't mention the session_id parameter, but the schema's description ('Reuse the same string across a task to accumulate memory') covers that. There is no output schema, so no return-value description is needed. The only minor gap is a lack of explicit mention of unpinning behavior when pinned=false, but that is inferred.

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 covers all four parameters with descriptions, so the baseline is 3. The description adds meaningful context by explaining the purpose of each action beyond the schema's dry definitions ('survive compaction', 'stops polluting recall'), which helps agents understand the semantic intent of the boolean flags.

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 action (pin, unpin, or delete) on a specific resource (a single entry by id), with a concise rationale for each. It distinguishes itself from siblings like context_compact and context_recall by focusing on single-entry mutation rather than bulk operations or retrieval.

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 guidance on when to pin versus delete ('Pin what must survive compaction; delete what turned out to be wrong'), which serves as an implicit usage test. It does not explicitly contrast with sibling tools like context_compact, but the context is sufficient for most agent decisions.

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 burden of transparency. It discloses the destructive and irreversible nature ('permanently delete') and the scope ('everything derived from it'), which are critical side effects. It does not mention permissions or errors, but it covers the most important behavioral aspects for a deletion 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?

The description is two concise sentences with no redundancy. The primary action is front-loaded, and the usage guidance is appended cleanly, making it easy to parse quickly.

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 simple deletion operation with one parameter and no output schema, the description fully covers what the tool does, when to use it, and the nature of the parameter. Nothing essential is missing for an agent to correctly invoke 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?

The single parameter doc_id is described as 'Document id returned by doc_ingest', which adds context on how to obtain a valid value. Since schema coverage is 100% and the description reinforces the source, it goes beyond a bare identifier definition.

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 action ('permanently delete') and the target ('an ingested document and everything derived from it'). It distinguishes itself from sibling tools like doc_ingest, doc_search, and doc_list by focusing on deletion and its cascading effect.

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?

Explicitly provides use cases: 'Use when a document is stale or was ingested by mistake.' This gives clear guidance on when to invoke this tool versus other document operations, with no ambiguity.

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 behavioral transparency burden and does it well: it reveals the key non-obvious behavior that content stays on disk rather than being loaded into context, and that it is split into addressable chunks. It also discloses the return value (a document id) and the ingest-root requirement. One smaller behavior, doc_id replacement removing existing stored content, is only present in the schema rather than the description, so the transparency is very good but not perfect.

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?

Every sentence earns its place: purpose in sentence one, usage guidance and alternatives in sentence two, input modes in sentence three, and the return value in sentence four. The most critical facts are front-loaded, and there is no filler or repetition.

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 moderately complex tool with no annotations and no output schema, the description covers the full contract an agent needs: what the tool does, why it should be used, what the preconditions are, and what it returns. It also positions the tool within the wider workflow of doc_outline, doc_search and doc_window. Nothing essential for a correct invocation 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?

The input schema already has 100% description coverage with clear, self-explanatory parameter descriptions, so the structured data is doing most of the work. The description adds a conceptual cross-reference between inline text and file_path as alternative input modes, but this largely restates what the schema already says. Descriptively, it provides little beyond the schema baseline.

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, unambiguous action: 'Load a large text into the store and split it into addressable chunks.' It clearly distinguishes the tool from alternatives by saying it should be used instead of reading a large file into context, and it names the complementary paging tools (doc_outline, doc_search, doc_window). An agent can immediately understand what this tool does and how it fits with its siblings.

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?

'Use this INSTEAD OF reading a big file into your context' gives an explicit, direct rule for when this tool is the right choice. The description also explains the follow-up workflow, stating content stays on disk and is paged through with doc_outline, doc_search and doc_window, and it clarifies the file_path precondition regarding the ingest root.

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 the burden of behavioral disclosure. 'List' implies a read-only operation and the description states what is returned, but it does not mention ordering, pagination, session scoping, or how 'read positions' are calculated. This is adequate but not rich.

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?

One short sentence with no filler. The action verb is front-loaded and the sentence conveys the tool's purpose and output in a compact, scannable way.

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 parameterless listing tool, the description is largely complete: it states scope ('ingested documents') and return fields. However, there is no output schema and no clarification of what 'read positions' means, leaving minor ambiguity. Still, an agent can likely invoke it correctly without additional context.

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 has zero parameters, so there is nothing to document beyond the schema. The description focuses on output rather than inputs, which is appropriate here. The baseline of 4 for zero-parameter tools is met.

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 ('List') and resource ('ingested documents') and names the exact return fields (ids, sizes, read positions). This clearly differentiates it from sibling tools like doc_search, doc_summarize, or doc_ingest.

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 use case is implied by the verb 'List' but there is no explicit guidance on when to choose this tool over siblings such as doc_outline or doc_window. No alternatives, exclusions, or prerequisites are mentioned.

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

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

Annotations are absent, so the description carries the full burden. It does disclose the performance cost of the summarize flag ('runs the summarizer once per chunk... slow on large documents'), which is a behavioral trait. However, it does not state whether the operation is read-only or has side effects (e.g., caching is mentioned only in the schema, not here), nor does it address error behavior for invalid doc_id. For a no-annotation tool, this is a moderate disclosure, hence a 3.

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 extremely concise: two sentences total. The first sentence front-loads the core purpose and output contents, while the second gives workflow context and a cost warning. Every clause earns its place, with no repetition or filler. Structure is ideal for quick agent consumption.

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 that there is no output schema and no annotations, the description must explain behavior and expected outputs. It covers the main purpose, when to call it, and the summarization cost. It explicitly lists the output components (chunk index, heading, size) and hints at the workflow. It does not describe the exact return format (e.g., list vs. map) or error cases, but for a simple outline tool this is largely sufficient. A 4 reflects that it is nearly complete without going overboard.

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 already documents all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds a performance note about the summarize parameter, which goes beyond the schema's simple 'generate and cache a short summary'. However, it does not add any meaning to doc_id or max_chunks beyond what the schema provides. The added value is limited but present, so a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Show the structure of an ingested document' and enumerates exactly what the result contains ('every chunk with its index, heading and size'). It clearly distinguishes its role from siblings like doc_summarize (whole-document summary) and doc_search by framing it as a structural overview. The purpose is unambiguous and fully stated in the first sentence.

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 an explicit when-to-use instruction: 'Call this right after doc_ingest to decide what is worth reading.' This tells the agent the exact workflow position and decision purpose. It also implies not to use it for other tasks and provides a trade-off for the summarize option. This is direct, actionable guidance that prevents misuse.

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 well: it discloses that results are 'verbatim' (not summarized), that output is 'packed into a token budget' (tied to budget_tokens), and that omitting doc_id searches the entire corpus. This gives an agent a clear picture of side-effect-free read behavior, though it omits error handling and ranking details.

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 with a striking analogy; every sentence carries information. The purpose is front-loaded, the usage nuance follows, and the parameter hint lands last. The manual-vs-index analogy, while colorful, earns its place by making the search-vs-paging tradeoff instantly understandable.

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 search tool with no output schema and no annotations, the description covers the essential behavioral contract: what is searched, what is returned, and how the token budget applies. It doesn't specify default values for limit or budget_tokens, but optional parameters and the schema make that a minor gap. Overall it's complete enough to call 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 100%, so the schema already documents each parameter. The description adds value by introducing the 'token budget' concept that clarifies budget_tokens and by restating doc_id omission as a scoping rule. This goes beyond the schema without duplicating it, showing good use of the complementary role.

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 clear verb and resource: 'Find the chunks of a document most relevant to a query and return them verbatim, packed into a token budget.' This makes the tool's purpose unmistakable. It gestures at a distinction from 'paging' through documents, though it doesn't name a specific sibling, so differentiation is strong but not explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs when to use the tool: 'Prefer this over paging when you know what you are looking for,' and reinforces it with the manual-vs-index analogy. It guides the agent away from using it for exploratory browsing and gives a concrete scoping rule ('Omit doc_id to search across every ingested document'). It falls short of naming the exact sibling tool to use instead, keeping this from 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 carries full burden. It discloses a useful non-obvious behavior: the whole-document summary is cached, making repeat calls cheap. It doesn't explicitly state read-only side effects, but the summarization framing implies a non-destructive operation.

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 tightly written sentences, each serving a distinct purpose: what it does, when to use it, and an optimization note. The core action is front-loaded, and there is zero 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?

Adequate coverage for a summarizer—description covers the action, use case, and a performance trait. It could mention the return format or error behavior, but no output schema exists, and the agent has enough to call it correctly. Slightly more detail on the default target_tokens would have made it a 5.

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 all parameters are documented. The description adds contextual value by explaining the caching model ('cached, so asking again is free'), which clarifies the refresh parameter's purpose and the cost model. This goes beyond the schema's field-level 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?

States a specific verb ('Summarize') and a clear resource ('a whole document or a range of its chunks'), and frames it as a gist-gathering step before verbatim retrieval, which differentiates it from sibling tools like doc_search or doc_outline. The language 'get the gist' clarifies exactly what problem it solves.

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 a clear use case: 'Use this to get the gist of something too large to read, before deciding which parts to pull verbatim.' This implies when to use it (large documents) and hints at alternatives for verbatim extraction, though it doesn't name them explicitly. Lacks an explicit when-not-to-use, so not 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 burden of behavioral disclosure. It reveals important stateful behavior: the read cursor is stored server-side, so sequential paging works without the agent tracking position. It also explains budget behavior and the verbatim read nature, which is strong 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?

The description is three sentences with no filler. It front-loads the core purpose, then adds the operational pattern and cursor behavior in a compact, readable way. 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?

The tool has moderate complexity due to its server-side cursor and budget parameter, and the description covers these well. There is no output schema, but the description does not need to fully specify return format because the read semantics and paging behavior are clear. Minor gaps like error behavior or what happens on a fresh cursor are acceptable.

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 adds value beyond the schema by explaining how from/to relate to sliding-window reads, and by clarifying that omitting them continues from the server-stored cursor. This extra context justifies an above-baseline score.

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 starts with a specific verb and resource: 'Read a range of chunks verbatim.' This clearly distinguishes doc_window from siblings like doc_search, doc_summarize, and doc_outline, which do not provide verbatim chunk reads. The sliding-window framing further clarifies its unique role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear practical usage context: it explains the sliding-window pattern, how to stay within budget, and how to continue paging by omitting from/to. It does not explicitly name alternatives or state when not to use this tool, 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.