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

No annotations are provided, so the description carries the full burden, and it never states that this is a read-only, side-effect-free operation, nor what happens when the page is absent in one of the versions. It does disclose a meaningful behavioral trait beyond the schema: from_version is the older key and to_version the newer one, which prevents reversed-diff mistakes. That partial disclosure earns a 3 rather than a 2.

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 states purpose before the arg list, and the Args block is tight with no redundant prose. The pseudo-Python formatting is slightly verbose for three parameters but every line adds 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 only three parameters, one required, and an output schema already covering the return shape, the description supplies exactly what is missing: purpose, parameter meanings, and examples. It omits edge-case behavior (unknown doc path, version not containing the page), which is a minor but real gap for a diff tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: 'doc' is explained as a page path OR doc_id with a concrete example ('items/index.md'), and both version params are defined semantically as older/newer with example keys. It stops short of explaining what the 'current' default means or how version keys are discovered, so not quite 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?

The first line gives a specific verb ('Diff'), a bounded resource ('one documentation page'), and the scope constraint ('between two versions'), plus a usage tag ('migration helper'). No sibling is named, but the version-comparison scope is inherently distinct from list_docs/get_doc/search_docs, so an agent can identify it 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?

'(migration helper)' implies the context of use, and the from/to framing tells the agent this is for comparing an older against a newer version. However, there is no explicit when-to-use statement, no when-not-to-use, and no pointer to a sibling for the case where the agent instead wants a single version's content (get_doc) or a full-text search.

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

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

With no annotations present, the description carries the burden and does disclose real behavior: matching order (exact match first, then substring) and the limit constraint (1-20, default 10). It omits any auth/permission notes, but for a read-only lookup that is a minor gap.

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, then a behavioral rule, then example inputs, then a compact Args block. Every line carries information and nothing is repeated from the schema.

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?

Both parameters are documented, the matching strategy is explained, and an output schema exists so return values need no elaboration. The only minor omission is behavior on zero matches or result ranking beyond substring, which is not critical for 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 0%, so the description must compensate, and it does: `symbol` is defined as the API identifier to look up, and `limit` gains meaning plus bounds (1-20, default 10) that the schema's bare integer does not provide. The symbol definition is slightly thin, so not a full 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+resource: finding usages/explanations of a Java/NeoForge API name, with concrete examples like "DeferredRegister" and "BlockEntity#saveAdditional". It does not explicitly distinguish itself from the sibling search_docs, leaving the agent to infer the difference, 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?

The "Good for ..." examples imply the appropriate query style, and "Exact match first, then substring" hints at when this tool is a fit. However, it never states when to prefer find_symbol over search_docs or when not to use it, 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?

No annotations are provided, so the description carries the behavioral burden, and it does disclose the return shape (markdown plus heading outline) and a size characteristic (15k+ chars). It does not state whether output is truncated at that size or that the operation is purely read-only, leaving a modest gap.

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

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

Front-loads the return contract and the routing rule before the Args block; every sentence carries information. No redundant restatement of the tool name or boilerplate.

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 not be re-explained, and the two parameters are well covered. The only gap is behavior at the stated 15k+ char scale — truncation, pagination, or splitting 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?

Schema description coverage is 0%, so the description must compensate for both parameters and largely does: doc_id is described as either a search_docs id or a path form ('items/index.md' / 'items'), and version is scoped to the path case with example keys including the default 'current'.

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 (Return) + resource (a whole documentation page) + output form (markdown plus heading outline). The word 'whole' implicitly contrasts with get_section, so an agent can distinguish this tool from its sibling without opening either schema.

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

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

Explicitly routes the agent: 'Prefer get_section unless the whole page is genuinely needed', and gives a concrete reason (pages reach 15k+ chars). This is a clear when-not-to-use statement naming the alternative.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the return shape (heading + body) and a cost relationship to get_doc, but says nothing about failure modes such as an unmatched or ambiguous heading, or whether doc_id must come from a prior search. Adequate but with real gaps for a no-annotation tool.

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

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

Purpose is front-loaded in the first sentence, the sibling comparison follows, and the Args block is tight and non-redundant. Slightly padded by the multi-line argument enumeration, but every line carries non-obvious 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 values need no explanation, and the description covers input semantics and relative cost thoroughly. The remaining hole is edge-case behavior (heading not found or ambiguous), which is a minor omission given the otherwise complete coverage.

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 compensate, and the Args block does so well: doc_id accepts either a search_docs id or a path form ('items/index.md' / 'items'), heading accepts an anchor, a heading title, or a distinctive path fragment, and version is conditional ('only used when doc_id is a path'). This is meaning the bare schema cannot convey.

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 one section, heading + body, of a documentation page) and explicitly names the sibling it is a narrower alternative to: 'Cheaper and more focused than get_doc.' An agent can distinguish it from get_doc, list_docs, and find_symbol 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 a clear selection signal versus get_doc ('cheaper and more focused'), implying this is the right tool when a single section suffices rather than a full page. It stops short of stating when not to use it (e.g., when you need multiple sections or the whole document), so no explicit 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?

No annotations are provided, so the description carries the full behavioral burden. "List every page" implies a complete, read-only enumeration with no pagination, but permissions, rate limits, and whether the result is truncated are never stated. Return-field coverage is also largely duplicative of 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?

Purpose and usage are front-loaded in two short sentences, followed by a compact Args block with no filler. The only minor waste is restating return fields (title, group, URL) that the output schema already conveys.

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 it covers scope, usage trigger, and both parameters. For a simple two-parameter list tool the only real gap is behavioral context (limits, auth) that no annotation supplies.

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%, yet the Args block documents both parameters: it gives concrete version-key values ("current", "1.21.1", ...) and enumerates the four valid section filters, which the schema does not constrain at all. It only omits what omitting section does, which is adequately implied by "optional filter".

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 gives a specific verb, resource and scope: listing every page of a documentation version, including returned fields (title, group, URL). It is clearly distinguishable from get_doc/get_section, though it never names a sibling explicitly, so it stops short of a 5.

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

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

"Useful for browsing or checking whether a page exists before searching" gives a concrete when-to-use condition that implicitly routes keyword lookups to search_docs. There are no explicit exclusions or prerequisites (e.g. auth), so it is clear context rather than full when/when-not 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?

No annotations are provided, so the description carries the burden, and it does disclose useful behavior: ranked snippet+URL results, a 1-12 limit with default 6, and the meaning of each version value including the concrete 'current' (26.1). It says nothing about permissions, result size, pagination, or whether queries are fuzzy, so a meaningful gap remains for a read tool whose output schema is present.

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 every Args line carries information not present elsewhere. The Args block itself is a slightly clunky format, but nothing pads or repeats unnecessarily.

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 5 parameters, one required, no annotations, and an output schema already covering return values, the definition supplies enough to invoke the tool correctly: full parameter semantics and version/section vocabularies. It stops short of saying when to prefer it over the get_*/find_symbol siblings.

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 all parameter meaning — and it does. It defines query with concrete examples, enumerates the section filter values ('docs', 'toolchain', 'user', 'modpack') that the schema does not constrain, gives the limit range 1-12, and explains mode='text' vs 'api'.

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 (NeoForge docs) plus the return shape (ranked section snippets with URLs), which is more than a restatement of the name. It does not explicitly distinguish itself from siblings such as get_doc, get_section, or find_symbol, so an agent must infer the split itself.

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: the parameter documentation (section filters, mode='api', version options) hints at when each option applies, and mode='api' gestures toward identifier lookup. There is no explicit statement of when to choose this over get_doc/get_section/find_symbol, nor any exclusions.

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