zim_get

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

With no annotations provided, the description carries the full behavioral burden and delivers extensively: it discloses branch-locking (view locked to 'full' when binary=True), failure modes (non-full view/content_offset in batch returns invalid_path_combination), oversize handling (truncated: true with metadata), and that compact_budget is never forwarded. The dedicated ERRORS section adds defense-in-depth context about rejecting flattened wire-schema payloads. No behavioral trait relevant to safe invocation is omitted.

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

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

The description is long but every section earns its place given 10 parameters, four branches, and zero annotation/schema support. The critical routing instruction ('EXTRACT the right path-shape before calling') is front-loaded, followed by tightly grouped PARAMETERS, RESPONSE, and ERRORS sections. Minor redundancy where mutual-exclusion is restated in both the branch list and parameter list reads as deliberate reinforcement for small models, not bloat.

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 high-complexity tool with 10 parameters, four exclusive branches, no annotations, and no output schema, the description is remarkably complete: it covers all branch conditions, every parameter's semantics, per-branch response types, truncation/pagination hooks, and structured error behavior. The only mild gap is that the named response dicts' fields aren't enumerated, which is minor given the tool's complexity and everything else disclosed.

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% — the schema has zero descriptions — so the description must fully compensate, and it does. Every parameter is explained beyond its type/default: view's enum values are expanded with concrete meanings (full markdown body, short snippet, heading tree, flat section list), max_content_length gets a 10MB default plus truncation semantics, content_offset gets its interaction with the truncation footer hint, and entry_path/entry_paths/main_page get explicit mutual-exclusion rules.

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

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

Opens with specific verb+resource: 'Fetch entries from a ZIM archive' and enumerates four mutually-exclusive branches (single body, binary, batch, main page). The ALIASES section maps natural-language phrasings ('get article', 'fetch', 'summary of X') to this tool, reinforcing exactly what it does. It clearly positions this as the general entry-fetching tool distinct from siblings like zim_query and zim_search.

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 branch rules tell the agent exactly which parameter combination to pass for each use case, and the ALIASES section instructs 'Route through THIS tool with the matching branch' — strong when-to-use guidance. It also draws one explicit boundary against a sibling: compact_budget is 'inert here — never forwarded. Only zim_query honors it.' However, it never says when to prefer zim_search or zim_get_section, so external alternative routing is incomplete.

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