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

Beyond the annotations (which only say not read-only and not destructive), the description reveals a stateful precondition: the target list must be open and the stack cache needs an item. This is useful hidden behavior. It stops short of describing failure behavior or exact insertion semantics.

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 concise sentences with the core action front-loaded and useful prerequisites in the second sentence. A minor redundancy exists because 'inserts new list items' restates 'Add list items', keeping it a 4 rather than 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 key stateful requirement is mentioned, but the description relies on the unexplained 'stack cache' concept and never ties the tool to the open_list_in_docling_document lifecycle. An agent could infer the ordering, but the description itself leaves that 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 the schema already documents document_key, list_items, list_item_text, and list_marker_text. The description mentions 'specified text and marker' but adds no meaning beyond the schema, matching the 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 names a specific verb ('Add'), a concrete resource ('list items'), and a precise target ('open list in an existing document in the local document cache'). This clearly separates it from sibling tools like open_list_in_docling_document, close_list_in_docling_document, and add_paragraph_to_docling_document.

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 states the context clearly: the document must already exist, the list must be open, and the document's stack cache must contain at least one item. It does not explicitly say 'call open_list_in_docling_document first' or list exclusions, so it is not a perfect 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?

Annotations already indicate this is a mutating operation (readOnlyHint=false, destructiveHint=false). The description adds that the paragraph is inserted 'under the specified section header and level,' but the input schema has no parameters for a section header or level, making this claim confusing and under-specified. No further behavioral detail is provided about positioning, ordering, or side effects.

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 front-loaded, with the core action in the first sentence. However, the two sentences are somewhat redundant: 'existing document in the local document cache' and 'already been processed and stored in the cache' convey nearly the same 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?

An output schema exists, so return-value details are not necessary here. However, the description references a 'specified section header and level' without explaining how those are supplied, since neither appears in the input schema. It also does not indicate how the paragraph anchors to existing document structure, leaving an important invocation gap for a mutation tool in a large sibling family.

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 the schema already documents both parameters. The description reinforces that document_key identifies a cached document and paragraph is the text content, but adds no additional formatting, syntax, or location semantics beyond what the 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 names a specific verb and resource: 'Add a paragraph of text to an existing document in the local document cache.' It also mentions placement 'under the specified section header and level,' which helps distinguish it from sibling tools that add titles, headings, or list items, though it does not explicitly contrast them.

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

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

The description gives a clear precondition: the document must already be processed and stored in the cache. However, it does not state when to prefer this tool over sibling tools like add_section_heading_to_docling_document or add_list_items_to_list_in_docling_document, nor does it provide any explicit when-not-to-use 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?

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds that the tool 'inserts' a heading into an existing cached document, which is useful. However, it does not explain where the heading is inserted, whether it appends at the end, or how it interacts with existing document structure.

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 compact and front-loaded with the core purpose. The additional sentences clarify the cache prerequisite and heading-level semantics without unnecessary verbosity. 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 simple three-parameter mutation tool with an output schema and clear annotations, the description adequately covers the purpose, prerequisite, and heading-level behavior. The main missing detail is insertion position, but this is a minor gap given the tool's simplicity and the availability of structured schema information.

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 documents all parameters well. The description adds a small clarification that section levels represent heading hierarchy with examples like H1 and H2, but most parameter meaning is already present in the schema. This matches the baseline for high schema 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 states a specific action and resource: 'Add a section heading to an existing document in the local document cache.' It is clear this tool modifies an existing Docling document by inserting a heading. It does not explicitly differentiate itself from sibling tools like add_title_to_docling_document, but the term 'section heading' and the concept of heading levels provide enough distinction for a clear purpose.

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 indicates that this tool is for documents 'already been processed and stored in the local cache,' establishing the prerequisite context. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to know when this tool applies.

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

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

Annotations already establish that this is a mutating (readOnlyHint=false) but non-destructive (destructiveHint=false) operation. The description adds useful behavioral context: it parses the HTML, converts it to a structured table representation, and supports captions and footnotes. It does not disclose potential failure modes or what happens on invalid HTML, but it goes beyond the annotations enough to avoid a lower score.

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 compact, front-loaded with the core action, and each sentence adds distinct information. There is slight redundancy ('adds it to the specified document' echoes the first sentence), but almost no wasted words.

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 an output schema and fully documented inputs, the description covers the core operation, the transformation process, and optional features. It lacks explicit usage guidance and error-behavior notes, but the overall context signals and schema fill most gaps needed for correct selection and 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 100% and examples are provided for html_table, so the schema already documents each parameter thoroughly. The description adds no significant parameter-level meaning beyond repeating that captions and footnotes are optional. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Add an HTML-formatted table to an existing document in the local document cache.' It also explains the mechanism (parses HTML, converts to structured table) and this clearly distinguishes it from sibling add_title/add_paragraph/add_list_items tools. The name and description align perfectly.

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 implies when to use the tool: when you have an HTML table string and want to attach it to an existing cached document. However, it does not explicitly mention when not to use it, nor does it reference alternative sibling tools for adding other content types. Usage guidance is 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?

Annotations already indicate this is a mutating but non-destructive operation. The description adds valuable context by specifying that the tool modifies an existing cached document and requires the document to already exist. This goes beyond the raw annotation flags and clarifies the operational precondition.

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

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

The description is concise and well-structured, with the primary purpose stated in the first sentence and the key prerequisite clarified in the second. There is no redundant or filler content; every sentence adds relevant 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 simple tool with two required, fully described parameters and an output schema, this description is complete. It states what the tool does, where it operates, and the critical precondition for use. Nothing essential is missing for an agent to invoke it 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 already provides 100% coverage for both parameters, including descriptions for 'title' and 'document_key'. The tool description doesn't add much beyond the schema, but the prerequisite about the document already existing in the cache slightly reinforces the meaning of document_key. This meets the baseline for fully documented 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 a specific verb ('add or update') and resource ('title of a document in the local document cache'), making the tool's purpose unambiguous. It also explicitly says it modifies an existing document, which distinguishes it from creation-focused siblings like create_new_docling_document.

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 usage context: this tool is for documents already processed and stored in the local cache, and it requires the document to exist before adding a title. It does not explicitly name alternatives or state when not to use it, but the prerequisite is clear enough to avoid 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered without help from the prose. The description is consistent with them and adds a small amount of context (it inspects conversion/cache state, it does not mutate), but says nothing about cost, cache scope, or behavior on a miss, which would be the value-add here.

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 with no filler; every clause (Docling, already converted, local cache) carries information.

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

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

With an output schema present, the description need not explain return values, and one required parameter plus read-only annotations leave little else to cover. A brief note on how this relates to the conversion tool would close the 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?

Only one parameter and the schema documents it fully ('The unique identifier of the document in the local cache'). The description adds no meaning beyond that, so the baseline 3 for high schema coverage 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?

Specific verb ('check') plus resource ('Docling document in the local cache'), with the clarifying detail that 'converted' means already present. It is distinguishable from convert_document_into_docling_document and list_cached_documents, but the description never names those siblings, so the differentiation is inferred rather than stated.

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 phrase 'already converted' hints at a pre-conversion probe workflow, but there is no explicit statement of when to call this versus convert_document_into_docling_document or list_cached_documents, and no mention of what to do on a miss.

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

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

Annotations already indicate this is a non-read-only, non-destructive operation. The description adds useful behavioral context by disclosing the stack cache requirement and that it closes a previously opened list structure, which helps the agent understand it is a state-changing 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?

The description is short and front-loaded, with the core action in the first sentence. The second sentence is somewhat redundant with the first, but it adds the 'previously opened' and 'stack cache' nuance, so the slight overlap is acceptable.

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 one-parameter mutation tool with an output schema and annotations covering read-only/destructive hints, the description provides enough context: what it closes, where, and the required preconditions. It does not explain error handling, but that is not essential for an agent to call it 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 100%, with document_key already described as the unique identifier of the document in the local cache. The description reinforces that the document must already exist, but does not add meaningful new parameter-level semantics 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 uses a specific verb ('closes') and resource ('list group in an existing document in the local document cache'), and clarifies it operates on a previously opened list structure. This clearly differentiates it from sibling tools like open_list_in_docling_document and add_list_items_to_list_in_docling_document.

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 concrete preconditions: the document must exist and the stack cache must have more than one item. It implies the tool should be used after opening a list and adding items, though it does not explicitly name alternatives or state when not to use it.

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?

Beyond the annotations, the description discloses caching behavior, the skip-if-cached rule, the boolean semantics per output, and the configured converter source (remote API or local). This is exactly the behavioral context an agent needs to predict the side effects and return values.

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 one-sentence summary is front-loaded, and the second paragraph earns its place by specifying return structure and cache behavior. There is no filler or redundant restating of the tool name.

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 single-parameter tool with an output schema, the description is largely complete: it covers the operation, storage, return shape, and caching. It does not mention how invalid or non-existent directories are handled or whether subdirectories are included, but these are secondary for correct tool 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?

The only parameter, source, is already fully described in the schema as 'The path to a local directory.' The description repeats this but adds no new format, resolution, or requirement details, so it does not improve on the schema's 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 names a specific action—convert all files from a local directory—and a specific outcome: store resulting Docling documents in local cache. It clearly distinguishes itself from sibling convert_document_into_docling_document by operating on a directory rather than a single document.

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 states the condition for use: the caller has a local directory path and wants every file in it converted. It implies rather than explicitly states the alternative of using convert_document_into_docling_document for a single file, so it lacks explicit when-not guidance but is not ambiguous.

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 only provide readOnlyHint=false and destructiveHint=false. The description adds substantive behavior: conversion uses a configured remote or local converter, results are stored in a local cache, cache hits skip conversion, and the output boolean signals cache-hit status. This is consistent with the 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 purpose is front-loaded in one sentence, followed by when-to-use and cache/return behavior. There is no filler, and the structure makes the key information easy 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?

An output schema exists, so the description need not fully document the return payload, but it still clarifies the boolean and cache-key behavior. Source, conversion path, cache semantics, and rerun behavior are all covered 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%, and the schema already documents the source parameter including object-storage URI support. The description repeats URL or local path and adds file-type examples, but it does not add syntax or constraints beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource, converting a document into a Docling document, and frames the scope around an existing file to load and parse. This distinguishes it from sibling tools such as create_new_docling_document and directory conversion.

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 says when to use it: an existing PDF, DOCX, HTML, image, etc. that the agent wants to load and parse. It does not explicitly name alternatives or when not to use it, so it stops short of full routing 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?

Annotations already declare this is a non-read-only, non-destructive operation. The description adds useful behavioral context: the document is stored in the local cache under a unique key and the prompt is recorded as a furniture item. It does not cover permission or persistence details, but those are less central here.

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 compact and front-loaded: primary purpose first, then usage guidance, then the sibling alternative, then storage behavior. Every sentence contributes useful 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?

Given the simple one-parameter schema, existing output schema, and annotations, the description provides everything needed: creation semantics, incremental authoring context, alternative tool routing, and local cache behavior.

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 single prompt parameter is already documented. The description adds meaning by explaining that the prompt text becomes a furniture item for reference, going beyond the schema's plain input description.

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 a specific verb and resource: create a new, empty Docling document. It also distinguishes this from the sibling conversion tool and names the downstream authoring tools it is meant to precede.

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 explicit when-to-use guidance for incremental authoring from scratch and names the alternative convert_document_into_docling_document for existing files. This directly routes the agent between sibling tools.

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?

The destructiveHint annotation already signals that this operation mutates or destroys, so the description's added value is the cache prerequisite and the anchor-based scoping of what gets deleted. This provides useful behavioral context beyond the annotations and does not contradict them.

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 front-loads the operation in the first sentence. There is slight redundancy between 'Delete multiple document items identified by their anchors' and 'removes specified items ... based on their anchor references,' but it remains appropriately sized and easy 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?

This is a simple two-parameter destructive tool with full schema coverage and an output schema. The description covers what the tool does and the important cache requirement, so an agent can safely select and invoke it. A slightly stronger description would also address invalid-anchor behavior or clarify whether deletion is irreversible.

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 coverages is 100%: document_key and document_anchors are both well-described, with examples such as '#/texts/2' and '#/tables/1'. The tool description restates the anchor-based semantics but does not add significant meaning beyond what the schema already provides, so the baseline score 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 first sentence states a specific verb ('Delete') with a precise resource ('document items') and selection mechanism ('anchors'). It also clarifies that this operates on a Docling document in the local cache and can remove multiple items, making it clearly distinguishable from sibling read/update tools.

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 conveys the main use case: deleting multiple cached document items by anchor references. It also states an explicit prerequisite: the document must already exist in the local cache. It does not name sibling alternatives or provide when-not-to-use guidance, but the destructive use case is obvious among the listed siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the source must exist in the local document cache and that output is a markdown string, but says nothing about failure when the key is absent or about size limits beyond the schema's own max_size field.

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 core action, and the page_no hint is placed after the main statement. The clause 'which can be used for display or further processing' is filler that could be trimmed, but overall it is tight.

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

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

With an output schema present, the description needn't explain return values, and annotations cover the read-only profile. It is complete enough for a straightforward export tool, though a note on behavior for missing or uncached document keys would close the 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 all three parameters are already documented, including page_no's 1-based semantics and max_size's character cap. The description's page_no note duplicates the schema rather than adding meaning, 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 — export a cached Docling document to markdown — and the conversion to a markdown string makes the output distinctive among siblings like get_text_of_document_item_at_anchor. It doesn't explicitly contrast with any sibling, but the purpose 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?

The only guidance is 'Set page_no to export a single page instead of the whole document', which is parameter usage rather than when-to-use-this-tool guidance. No mention of when to prefer other extraction tools (e.g., anchor-based text retrieval) or prerequisites such as the document already being in the cache.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral detail: it operates on the local document cache and returns line-level output containing anchor references and item labels. This is proportionate for a read-only tool and does not contradict the 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 compact and front-loaded with the main action and resource. The second sentence adds specific output details—hierarchy, types, anchor reference, and item label—without any filler. 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 single-parameter, read-only overview tool with complete input schema documentation, annotations, and an output schema, the description sufficiently covers source, behavior, and output format. Nothing essential is missing for an agent to invoke it 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 100%: document_key is already described as 'The unique identifier of the document in the local cache.' The description's phrase 'from the local document cache' reinforces this but adds no additional parameter semantics beyond what the 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 'Retrieve a structured overview of a document from the local document cache' and then explains that the output is a text representation of the document's hierarchy and element types, with each line containing an anchor reference and item label. This clearly identifies the action, resource, and output, and differentiates it from sibling content-retrieval or mutation tools.

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 usage context is implied: use this when you need a structural overview of a cached Docling document. However, there is no explicit statement of when to prefer this tool over alternatives such as search_for_text_in_document_anchors or get_text_of_document_item_at_anchor, and no 'when not to use' 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that the thumbnail is derived from a local-cache document, but says nothing about whether the thumbnail is persisted/side-effecting, what format is returned, or any cost/size considerations—important for a 'generate' verb.

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 with no filler. Nothing is redundant or buried.

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?

No output schema exists, so the description should explain what the thumbnail return looks like (image bytes, URL, base64, MIME type) and any prerequisites. It covers neither, leaving the agent guessing about the result shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with size, page_no, and document_key fully documented, so the schema carries the burden. The description only echoes 'requested page' without adding defaults, units, or format semantics 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?

States a specific verb+resource: generating a thumbnail image for a requested page of a cached document. It's distinguishable from the anchor/text-reading siblings in the toolset, though it doesn't say how it relates to get_overview_of_document_anchors or other read tools.

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 explicit guidance on when to use this versus alternatives, and no stated precondition that the document must already be in the local cache (e.g., via check_document_in_local_cache or convert_document_into_docling_document). The phrase 'in the local cache' only hints at the requirement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful context by specifying that the document must exist in the local document cache and that extraction is targeted at an anchor location, which helps the agent understand prerequisites.

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 front-loaded with the core purpose in the first sentence. The second sentence repeats some of the same information, but it adds useful cache context, so the slight redundancy is acceptable.

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 read-only tool with a full input schema, output schema, and safety annotations, the description is largely complete. It covers the key prerequisite of cache residency, though it does not explain behavior for invalid or missing anchors; that is a minor 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%, with both document_key and document_anchor already described clearly, including an example anchor format. The tool description adds no parameter-level meaning beyond what the schema provides, so the baseline score 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 uses a specific verb ('Retrieve'/'extracts') and names the precise resource: text content of a Docling document item at an anchor. It stands apart from siblings like update_text_of_document_item_at_anchor and search_for_text_in_document_anchors by clearly focusing on read-only text extraction.

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 implies when to use the tool: after a document exists in the local document cache and when you need the text of a single anchored item. However, it gives no explicit guidance about alternatives or when not to use it, such as when needing to search anchors or update text.

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

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

Annotations already cover the read-only, non-destructive safety profile, and the description reinforces this by framing the tool as pure discovery. It also discloses the empty-list edge case, which is behavior an agent needs. It doesn't discuss ordering or whether keys are stable across cache reloads, though an output schema exists to cover the return shape.

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 short sentences, front-loaded with the core action, then usage context, then the edge case. No filler and nothing repeated from structured fields.

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 read tool with annotations and an output schema, this covers everything an agent needs: what it returns, when to call it, and how to recover from an empty result.

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?

Zero parameters, so baseline is 4. The description usefully links the returned keys to the document_key argument expected by other tools, giving the agent a reason for the output even though no input semantics apply.

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 ('Return the keys of all Docling documents currently held in the local cache') with explicit scope (local cache, all documents). This distinguishes it from siblings like check_document_in_local_cache (single lookup) and remove_document_from_local_cache (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 says when to use it ('discover which documents are available before calling any tool that requires a document_key') and what the empty-list outcome implies. It even names the two alternative entry points (convert_document_into_docling_document, create_new_docling_document) that populate the cache.

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 only say readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing stack semantics, the error condition for misordered calls, and the nesting/close-order protocol. This is exactly the kind of state-machine behavior an agent cannot infer from the schema.

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 the core action, then the constraint, then the nesting rule. No filler and no repetition of the schema or annotations.

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?

Output schema exists so return values needn't be explained, and the description covers the one thing that matters for this low-parameter tool: the ordering contract and the legal next call. Nothing needed for 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?

Schema coverage is 100% and the single document_key parameter is fully described in the schema, so the description adds nothing new about it. With one well-documented parameter, the baseline 3 applies rather than a penalty.

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 ('Open a new list group') and scopes it to 'an existing document in the local document cache'. The stateful-stack framing clearly distinguishes it from add_list_items_to_list_in_docling_document and close_list_in_docling_document among the 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?

Explicitly names the only legal follow-up call (add_list_items_to_list_in_docling_document) and lists the calls that will raise an error instead (title, section heading, paragraph, another list). It also documents the nested-list sequence and the required reverse-order closing, so the agent knows both when to use it and what must come next.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's added post-condition ('after a successful call the key is no longer present in the cache') is genuinely useful state-transition context. It stops short of covering the no-op/error case when the key is absent or whether the operation is idempotent.

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 short sentences, front-loaded with the action and effect, with zero filler. Every sentence contributes action, trigger, and post-condition.

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?

An output schema exists, so return values need no explanation, and the description covers the trigger, effect, and post-state. Only the absent-key/error behavior is left unaddressed, which is a minor gap for a one-parameter cache removal.

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% and the single parameter is documented as 'the unique identifier of the document to remove from the local cache'. The description adds no format, origin, or constraint detail beyond that, 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: removing a document from the local cache and releasing its memory. It is clearly distinguishable from document-editing siblings like delete_document_items_at_anchors, and its cache-management kin (check_document_in_local_cache, list_cached_documents) are implicitly different in effect, though not 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?

Gives a clear trigger condition: call when a client is finished with a document and wants to release memory. It does not name an alternative (e.g., check_document_in_local_cache to confirm presence first) or state when not to call, so it falls short of full routing 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?

Annotations only say it is a non-read, non-destructive write, so the description carries real weight and it does: it discloses that two files are written, that filenames derive from the document key, and that page_no narrows only the markdown file while JSON stays complete. It never explains how the target 'cache directory' is determined or what happens on an overwrite, 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-loaded with the core action, then the page_no caveat. It is slightly repetitive, restating 'both markdown and JSON versions' after already saying 'in both markdown and JSON formats', but nothing is wasted enough to hurt.

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 only two parameters, full schema coverage, annotations for the write profile, and an output schema, the remaining need is explaining the dual-file write and page_no asymmetry — both are covered. The only soft spot, where the target directory comes from, is minor.

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 both parameters are already documented in the schema, including the page_no markdown-only nuance. The description restates rather than extends that meaning, so the baseline 3 applies.

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

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

States a specific verb+resource: saves a cached docling document to disk as markdown plus JSON, which is more specific than the title alone. It never names the near-identical sibling export_docling_document_to_markdown, so an agent must guess which is the right 'write to disk' tool.

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 phrase 'takes a document that exists in the local cache' implies the precondition (the doc must already be cached), which is useful usage context. But there is no explicit when-to-use/when-not guidance and no routing to or away from export_docling_document_to_markdown or check_document_in_local_cache.

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?

The description goes well beyond the readOnlyHint/destructiveHint annotations by explaining the exact search behavior: case-insensitive matching, fallback to splitting the input into keywords on non-alphanumeric characters, and reporting keyword occurrence counts. This gives an agent a clear model of what will happen.

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

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

The description is concise and well-structured, opening with the core purpose and then elaborating with necessary behavioral details. Each sentence adds useful information, with no redundant or filler content.

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 presence of an output schema, the description does not need to detail return values. It covers the main functionality, search behavior, and fallback logic. A possible gap is the absence of a stated behavior when neither the exact text nor any keywords are found, but this is a minor omission.

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%, with both parameters described in the input schema. The description adds context about the search behavior but does not add new semantic detail about the parameters themselves, 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 identifies the operation as searching for text within a document's anchors, using a specific verb and resource. It distinguishes the tool from siblings that retrieve or modify anchors, though it does not explicitly name 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?

The description implies when to use the tool: to find document anchors containing a specific text or keywords. However, it provides no explicit guidance on when to prefer this over related tools like get_overview_of_document_anchors or get_text_of_document_item_at_anchor.

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

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

Annotations already declare this as mutating and destructive, so the description does not need to repeat that. It adds useful behavioral context by explaining the target must be an existing document item and that the document must already be cached, which goes beyond the raw 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 concise, consisting of two short sentences that convey the primary action and the key prerequisite. It is front-loaded with the core purpose and contains no filler or redundant information.

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

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

With full schema coverage, an output schema, and annotations indicating destructive behavior, the description covers the essential operational context: the update targets an existing cached item by anchor. It could add a note about how to obtain valid anchors or the need to save after updating, but these are not critical gaps given the sibling tools and existing schema.

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 the schema already fully documents all three parameters: document_key, updated_text, and document_anchor. The description does not add parameter-level details beyond what the schema provides, so a baseline score 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 uses a specific verb ('Update') and resource ('text content of a specific document item identified by its anchor'), making the tool's function immediately clear. It also distinguishes this from sibling tools like get_text_of_document_item_at_anchor and delete_document_items_at_anchors by focusing on modifying existing text.

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 states that the tool requires the document to already exist in the local cache before modification, providing meaningful context for when it can be used. It does not explicitly mention alternatives or when not to use it, but the prerequisite is clear enough to guide the agent.

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