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

Annotations already declare readOnlyHint=true, setting a lower bar, and the output schema covers the return shape. The description adds only the behavioral nuance that kind skips guessing; it does not mention error behavior when the ID is invalid or whether lookup is scoped to a particular collection.

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 purpose sentence followed by a compact Args block; every line earns its place and there is no filler. The doubled list of item kinds is slightly redundant with the kind enumeration but not wasteful.

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 param plus one optional param are both documented. It is nearly complete for a simple lookup tool, missing only a note on failure behavior for unknown IDs.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: file_group_id is explained as "The ID from search results" and kind is enumerated ("video", "archive", or "doc") with the useful effect that supplying it "skips guessing". This adds real meaning beyond the bare integer/string 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?

Names a specific verb ("Get details") and resource ("one item of any kind (video, archived page, document)") scoped to retrieval by ID from search results. It is distinguishable from search_files and list_files, though it does not explicitly name which sibling to use instead of this one.

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?

"by its ID from search results" implies the tool is used downstream of a search and requires an ID obtained elsewhere, which is useful implied guidance. However, there is no explicit when-to-use versus read_content/read_file/get_zim_entry, and no stated preconditions beyond the ID source.

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, so the safety profile is covered. The description adds mode-dependent behavior beyond that — listing returns all inventories, while a slug read returns 'every item' in one inventory — which tells the agent what granularity to expect.

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 core dual-purpose statement is front-loaded and waste-free, with the parameter split into a short Args block. Slightly more structure than the content strictly needs, but nothing extraneous.

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-optional-parameter tool with an output schema (so return values need no explanation), the description covers both calling modes adequately. The only gap is not indicating how a slug is discovered.

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

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

Schema coverage is 0% and the single parameter has no schema description, so the description must carry the meaning — and it does: the argument is one inventory's slug, and its omission (the default null) switches to list-all mode. It doesn't explain slug format or where to obtain slugs, keeping it short of a 5.

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

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

States a specific verb (list/read) on a specific resource (inventories) and explicitly covers both operating modes. It's clearly distinguishable from file-, zim-, and map-oriented siblings, so an agent knows exactly what this returns.

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 tells the agent the selection rule directly: pass a slug to read one inventory in full, omit it to list all. That is concrete usage guidance, though it names no alternatives or when-not-to-use conditions.

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?

readOnlyHint=true already establishes that this is a safe, non-mutating read, so the description is not carrying the safety burden. It does add useful behavioral scope beyond the annotation by disclosing the four categories of data returned (downloaded regions, index availability, subscriptions, saved pins with links), which tells the agent what coverage to expect.

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 sentence, front-loaded with the verb and target, with the returned content listed compactly. Every clause earns its place and nothing is padded.

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 structure, and no parameters or risky behavior exist to document. The only real gap is the absence of any when-to-use routing against place/file siblings, which an agent might want in order to pick this overview over a targeted search.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The enumeration of returned content indirectly confirms it is a single-shot aggregate call with no filtering knobs.

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 ('Describe') and resource ('the maps on this WROLPi') and enumerates exactly what is covered: downloaded regions, place-search index presence, subscribed regions, and saved pins. It is clear enough to distinguish from lookup siblings like search_places or get_file, though it does not explicitly contrast itself with 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?

There is no statement of when to call this tool versus alternatives such as search_places (which presumably searches within the place index this tool describes). Usage is only implied by the subject matter; no prerequisites or exclusions are given.

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?

readOnlyHint=true already tells the agent this is a safe read with no side effects, so the bar is low. The description adds which content categories are summarized, but discloses nothing further about auth, scope of the library, or freshness of the counts - and the output schema already covers 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?

Two short sentences, zero filler, with the core purpose front-loaded and the returned content categories following immediately. Nothing needs to be cut.

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 no-parameter, read-only tool with an output schema defining the return values, the description covers what an agent needs to call it correctly. The only real gap is disambiguation from the similar get_inventory sibling, which is not addressed.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline is 4. No parameter-level information is missing or needed.

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?

Clear verb+resource: "Get an overview of what content is stored in the WROLPi library," then names the categories counted (videos, archives, ebooks, Zim files). However, it never distinguishes itself from the close sibling get_inventory (or get_status), which likely overlaps in intent.

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

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

Usage is only implied by the phrase "overview of what content is stored" - there is no explicit when-to-use, when-not-to-use, or pointer to get_inventory/get_status as alternatives. An agent must guess which sibling to call for aggregate information.

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 readOnlyHint annotation already establishes this is a safe, non-mutating read, and the description adds the useful detail that the payload is a bundled snapshot of several subsystems. It says nothing about cost, freshness, or whether it probes the system live versus returning cached values, which is the remaining behavioral question for a status 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?

One sentence, front-loaded with the verb and resource, with the detail folded into a compact parenthetical. Nothing is redundant and nothing needs to be trimmed.

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

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

With no parameters, no nesting, and an output schema present, the description does not need to explain return values or arguments, and its scope list is a helpful preview. It could add one clause on when in a workflow to call it, but nothing required 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?

The tool takes zero parameters and the schema has no properties to document, so the baseline is 4. The parenthetical list describes the shape of the response rather than any inputs, which is the correct use of description space 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?

States a specific verb ('Get') and resource ('WROLPi system status') and enumerates the categories returned (version, mode, download summary, CPU, memory, disks, flags). That enumeration clearly separates it from the file/search/ZIM-oriented siblings. It stops short of explicitly naming a sibling, but none of the siblings is close enough to be confusable.

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

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

Usage is only implied: an agent infers it should call this when it needs host-level system state rather than file or inventory data. There is no explicit when-to-use statement and no named alternative (e.g. get_statistics, which could plausibly overlap). Adequate but with a clear gap.

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 readOnlyHint annotation already establishes this as a safe read operation. The description adds useful behavior beyond that: output is plain text and offset can be used to continue reading, which helps an agent manage partial reads.

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?

Very concise and front-loaded: purpose, prerequisite, then parameter notes. Every sentence earns its place and there is no redundant restatement 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?

The output schema already covers return values, and annotations cover the safety profile. The description supplies the missing operational context: what is read, the plain-text output, the search_zim prerequisite, and offset continuation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does. It explains zim_id as the Zim file ID, entry_path as a path from search results, and offset as a character offset for continuing a read.

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: read a specific article/entry from a Zim file as plain text. It also distinguishes itself from search_zim by routing path discovery to that sibling, so an agent can tell what this tool is for without opening the schema.

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

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

Explicitly tells the agent to use search_zim first to find entry paths, which is the key prerequisite for invoking this tool correctly. It does not state when not to use it or name other alternatives, so it falls short of a full 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 declare readOnlyHint=true, so the safety profile is covered. The description adds that results are paged and that offset comes from a previous listing's 'next offset', which is useful operational context, but it omits ordering, total counts, and filtering behavior details beyond name matching.

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 summary sentence is front-loaded and the Args block is terse and scannable. There is minor redundancy in restating parameter names already in the schema, but no filler prose.

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 safety. Combined with the paging note and the full kind enumeration, an agent has enough to invoke this correctly; only ordering and total-count behavior are left implicit.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it enumerates the valid 'kind' values, explains 'query' as substring matching on names, and clarifies that 'offset' is sourced from a prior listing's 'next offset'. This is genuinely compensating for a bare schema.

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

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

The description states a specific verb and resource ('List collections ... in the library, paged') and enumerates exactly what a collection can be (channels, domains, playlists, authors, subjects). It distinguishes itself reasonably from siblings like list_tags or list_files by scope, though it doesn't explicitly name an alternative 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternatives. The agent must infer from the resource noun that this is the tool for browsing collections, but nothing steers it away from siblings like list_tags or search_files.

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?

readOnlyHint=true already declares the safety profile, and the description reinforces it with an explicit negative-capability statement ('cannot be started, stopped, or retried'), which is genuine added value for routing. It stops short of describing ordering or the shape of the queue summary, but the output schema covers returns.

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 resource, then usage, then exclusions, then compact arg definitions. Every sentence earns its place and there is no filler.

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

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

For a read-only listing tool with an output schema documenting returns and annotations covering safety, the description supplies everything needed: scope, use cases, exclusions, and both filter semantics.

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

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

Schema coverage is 0%, so the description carries the full burden and mostly does: it supplies the allowed status values (new, pending, failed, deferred, complete) that the schema's bare string lacks, and clarifies that limit caps recurring and one-time downloads separately. It omits the default of 10 and any interaction between the two filters.

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 ('Read the WROLPi download queue') and enumerates the three things it returns: summary, recurring downloads, one-time downloads. No sibling tool touches downloads, so the domain 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?

Explicitly names when to use it ('what is downloading, what failed and why, or what is scheduled') and draws a hard boundary with a when-not clause: downloads cannot be started, stopped, or retried from here. Nothing is left to inference.

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

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

Annotations only declare readOnlyHint=true, so the description adds real value: it discloses deterministic ordering (directories first, then files), that entries carry relative paths reusable as input, and that large directories are paged with an offset returned to the caller. It does not describe behavior for invalid or nonexistent paths, which is a minor gap given the read-only profile.

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 purpose in sentence one, followed by usage, ordering, and paging behavior, then a compact Args block. Mild redundancy in repeating 'media directory' across the body and the Args section, but nothing is wasted given the schema has no parameter descriptions.

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 need not be re-explained; the description still conveys the essential return semantics an agent needs (ordering, relative paths, next offset for paging). For a two-parameter read-only listing tool, this is complete enough to invoke correctly on the first try.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: path is defined as relative to the media directory with empty meaning top level, and offset is defined as the count of entries to skip taken from a previous listing's next offset. Both parameters gain meaning that the schema does not supply.

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

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

States a specific verb (list) and resource (directories and files inside one directory of the WROLPi media directory), with an explicit scope limitation to a single directory level. This is clearly distinguishable from siblings like search_files, get_file, and read_file without opening any schema.

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

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

Gives concrete usage context ('use this to explore how the library is organized on disk') with examples of paths, plus procedural guidance on descending via returned relative paths and continuing paged listings with the returned offset. It stops short of naming a when-not condition or explicitly routing to an alternative such as search_files for name-based lookup.

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 readOnlyHint annotation already establishes this is a safe read, so the bar is lower, and the description still adds real context: it discloses the aggregation shape (counts per tag across four entity types) and the extra output ('most recently used tag names'). It also reveals the cross-tool contract that tag names feed tag_names on the search tools, which is behavior no annotation or schema conveys.

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 with the core purpose front-loaded and no filler; the counts-and-usage facts each earn their place. The only mild inefficiency is the line break and slightly loose final clause about recently used tags, but nothing is redundant.

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 technically need no prose, yet the description still summarizes the aggregation semantics usefully. Combined with the readOnly annotation and the zero-parameter schema, an agent has everything required to call this correctly; only pagination or size expectations are unaddressed.

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

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

With zero parameters the baseline is 4 by rule, and the description does not need to explain any inputs. The only parameter-like mention is 'tag_names', which belongs to sibling search tools rather than this one, and it is correctly framed as a downstream usage hint.

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 ('List every tag in the library') and immediately specifies the returned payload (counts of files, Zim entries, channels, domains). No sibling tool in the list (list_files, list_zim_files, list_collections, get_statistics) overlaps with this scope, so an agent can route to it unambiguously.

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 motivates the tool ('Users tag what they care about, so this is a good map of their interests') and links its output forward ('Tag names can be passed as tag_names to the search tools'), which implies a discovery-then-search workflow. However, it never states when to prefer this over the many other list_* tools or any exclusion, so 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds that it returns Zim IDs required by downstream tools, which is useful context, but says nothing about pagination, ordering, or size of the listing beyond what the output schema presumably covers.

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 primary purpose and followed by the downstream relevance. No filler or repetition 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?

With no params, an output schema present, and annotations covering the safety profile, the description needs only to state purpose and downstream use, which it does. It could mention how the listing is scoped, but nothing essential 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?

The tool takes zero parameters, so there are no semantics to document; baseline for no params applies. The description correctly conveys that it is called with no filtering or input.

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

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

States a specific verb ('List') and resource ('Zim encyclopedias'), and clarifies the resource type with concrete examples (Wikipedia, Wiktionary). The mention of sibling tools search_zim and get_zim_entry lets an agent distinguish it from them immediately.

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?

Implies usage by stating the returned Zim IDs are 'needed for search_zim and get_zim_entry', which tells the agent this is a prerequisite/entry point tool. It stops short of explicit when-to-use/when-not guidance or any exclusions.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description goes beyond that by disclosing important behavior: long content is returned in windows and the agent must continue with the offset the result provides. That pagination/continuation contract is exactly the kind of detail annotations cannot carry, though auth or rate-limit context is absent.

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 operational summary is front-loaded in the first sentence, and the args list is compact with no filler. Slight redundancy between the prose mention of part and the args repetition, but nothing wasteful.

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 one required param, an output schema present, and readOnlyHint annotated, the description covers what an agent needs: what it returns, how to select a mode, and how to page. Return-value explanation is correctly omitted since the output schema handles it.

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

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

Schema description coverage is 0%, and the schema does not even mark allowed values for part, so the description has to do all the work. It compensates by documenting all three params: file_group_id's origin (search results), part's two valid values with default, and offset's role in continuing a read.

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 ("Read what an item says") and enumerates the two content kinds it can return: captions/archived page text and comments. It distinguishes content-reading from file-reading by describing the resource type, though it never names the sibling read_file to route the agent explicitly.

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 clear selection guidance for the two modes via "part='text'" vs "part='comments'", and "The ID from search results" implies the workflow (find via search, then read here). There are no explicit when-not conditions or named alternative tools, but the usage context is unambiguous.

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?

readOnlyHint=true already establishes this as a safe read, so the description isn't carrying the safety burden. It does add genuine behavioral context beyond the annotation: the 'Text files only' restriction and the fact that offset supports continuing a prior read. It omits size/truncation behavior and encoding, so it adds value but not richly.

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 sentence is front-loaded and the two parameters are listed compactly. There is no filler, though the 'Text files only' warning is tucked into the path line rather than surfaced as a standalone constraint an agent should notice.

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

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

With an output schema present, return values need not be described, and the description covers the location scope, file-type restriction, and both arguments. The main residual gap is the unaddressed overlap with sibling read/list tools, but for a simple two-parameter read this is close to complete.

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

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

Schema description coverage is 0%, so the description must do all the work, and it largely does: path is defined as relative to the media directory with a concrete example ('notes/todo.txt'), and offset is explained as a character offset to resume reading. The offset default of 0 from the schema is not echoed, and no units/bounds caveat is given, but both parameters are meaningfully documented.

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 ('Read a plain-text file'), plus the scoping detail that the file lives in the media directory and is addressed by relative path. It does not explicitly differentiate itself from siblings like read_content or get_file, which is the only thing keeping it from a 5.

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

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

The parenthetical '(from list_files)' implies the intended workflow and the source of valid paths, which is useful implied guidance. However, it never states when to choose read_file over read_content, get_file, or search_files, so the agent must infer the boundary between these overlapping 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 only declare readOnlyHint=true, so the description usefully adds that deep search is slower (on a Raspberry Pi), that limit is capped at 100, and that offset drives pagination. These are real behavioral traits beyond the annotation, though nothing about result shape or failure modes (partly covered by the output 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?

A single front-loaded summary sentence establishes scope, followed by a tight Args list where each line adds non-redundant meaning. 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?

With 10 optional parameters, zero schema descriptions, an output schema present, and only a readOnlyHint annotation, the definition covers everything an agent needs: scope, per-parameter meaning, cross-parameter implications, and the key performance trade-off. Return values are handled by the output schema, so nothing material is missing.

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

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

Schema description coverage is 0% for 10 parameters, so the description carries the full load — and it does: every argument is explained with semantics beyond its name (query searches titles vs captions/page text depending on deep, partial-match behavior for author/subject, and the implication relationships channel→video, domain→archive, author/subject→doc). This compensates completely for the empty 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 (search) and resource (the whole library) and enumerates the covered content types (videos, archived web pages, documents/ebooks), which implicitly separates it from narrower siblings like search_zim or search_places. It stops short of explicitly naming an alternative tool, so a 4 rather than a 5.

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

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

Gives concrete usage guidance: omit query to browse newest items, and use deep=True when a title search finds nothing (with the cost caveat). It also encodes implicit routing via 'channel implies kind=video' and 'domain implies kind=archive'. No explicit when-not-to-use or named alternative tool, so it falls just short of 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 declare readOnlyHint=true so the agent knows it's a safe read. The description adds behavioral detail beyond that: prefix-match semantics on the query and that each result links to the WROLPi map. It does not describe pagination behavior despite exposing offset, so it is only moderately additive.

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 key purpose sentence is front-loaded and the per-parameter notes are terse. The Args block restates structure the schema already has, but each line adds real semantic value rather than padding.

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

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

With an output schema present, return values need not be described, and the description covers all five parameters plus the read-only nature. What's missing is usage routing against siblings, but for a straightforward search tool the definition is nearly complete.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden, and it does so for all five: query as a prefix match with an example, limit as maximum results, offset as pagination, and lat/lon as ranking to prioritize nearby places. It omits defaults and the numeric ranges, which the schema supplies, so it largely compensates.

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 ('Find towns, cities, and landmarks by name') and scopes it to 'the downloaded maps', which is enough to distinguish it from the file/ZIM/inventory siblings. It stops short of naming a specific alternative, 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?

There is no statement of when to use this tool versus the many sibling search/get tools, nor any prerequisite or exclusion. Usage is only implied by the domain ('downloaded maps').

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, so safety is covered; the description adds the non-obvious behavioral nuance that an omitted zim_id silently restricts search to the subset of Zims with 'search by default' enabled, and that limit is applied per Zim when multiple are searched. It does not mention ranking, result ordering across Zims, or rate limits, so it stops short of full transparency.

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

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

The key scoping rule about default Zims is front-loaded in the second sentence, before the arg list, which is the right ordering. The Args block is somewhat redundant with the schema titles but each entry adds at least a small semantic increment, so little is wasted.

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 it correctly points to get_zim_entry for reading results. Combined with the default-Zim and per-Zim-limit notes, an agent has enough to call this correctly, though result ordering or multi-Zim aggregation behavior is unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does document all four parameters with meaning beyond the bare titles: zim_id's default-vs-specific behavior, limit as per-Zim when several are searched, and offset as pagination. Only 'query' is left at a trivial restatement with no mention of search syntax or matching behavior.

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 ('Search the Zim encyclopedias') and immediately scopes it with concrete examples (Wikipedia, Wiktionary). It is clearly distinguishable from adjacent siblings like search_files or search_places, and it names the downstream tool (get_zim_entry) for consuming results.

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

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

Gives an explicit when-branch: omit zim_id to search Zims with 'search by default' enabled, or pass one to target a specific Zim, with list_zim_files named as the source of that ID. It does not explicitly exclude any sibling search tool, so an agent still has to infer this is the encyclopedia-search niche rather than general file search, but the context is clear.

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