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

With no annotations, the description carries the full behavioral burden, and it discloses two genuinely useful traits: it merges exactly one level of <Base>, and it deliberately does NOT filter components (Projectile / DamageModel / Homing / ParticleEmitter are all kept). It remains silent on failure modes (missing/malformed XML) and permissions, but for a single-argument read tool the key behavioral surprise is covered.

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, with the follow-up sentences spent only on the merge rule and the no-filtering behavior. No filler or repetition; slightly longer than strictly necessary but every clause 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?

An output schema exists, so return-value explanation is rightly omitted, and the merge/filter behavior is documented. The remaining gap is the completely undocumented 'path' parameter, which is required for every call, leaving the definition just short of complete for its complexity.

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 sole parameter 'path' has no description in the schema, so the description is the only place that could define it. It never mentions 'path' at all — no format, no base directory, no indication of file vs. entity id — so the coverage gap is not compensated.

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 ('读取任意实体 XML') plus a non-obvious operation (merge one level of <Base>) and the result ('返回它的全部组件'). That is enough for an agent to tell it apart from a raw read like read_xml, though it never names read_xml or the spell/spell_bundle siblings 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?

'适合自己实现行为逻辑时逐个组件取值' implies the scenario where this tool is preferred, but it is stated as a suitability note rather than an explicit when-to-use / when-not-to-use rule. No alternative (read_xml, spell, spell_bundle) is named as a fallback for other cases.

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 burden. It does disclose a genuine behavioral trait (non-recursive traversal) and the fields returned, but says nothing about error handling for missing directories, permission/auth needs, or what an empty path resolves to.

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, with the scope constraint (non-recursive) front-loaded. The second sentence enumerating returned fields is mildly redundant given an output schema exists, but it is not wasteful enough to penalize further.

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 listing tool with an output schema present, the description covers purpose, scope, and return shape adequately. The remaining gaps are the default-path behavior and lack of any alternative-tool routing.

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% for the single path parameter, so the description must compensate. It partially does by implying the path is a directory relative to data/, but it never states whether the value is relative or absolute, or how the default empty string is interpreted.

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 gives a specific verb (列出/list), resource (data/ 下某个目录的直接子项), and explicit scope (不递归), so an agent immediately knows this is a directory-listing tool. It does not explicitly contrast itself with any sibling tool, so it falls short of the top tier.

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 用于定位文件 (to locate files); there is no statement of when to choose this over read_text, read_xml, or search. No prerequisites or when-not-to-use conditions 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?

With no annotations, the description carries the full burden and does fairly well: it discloses the line-oriented read model, that offset is 1-based, that limit caps returned lines, that total_lines is returned for pagination, and that binary input is rejected. It omits encoding assumptions, file-size limits, and error behavior on missing paths, but the core operational traits are 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?

Three compact clauses, front-loaded with the core action and then the parameter semantics, with zero filler. The Chinese phrasing packs the format list, pagination contract, and rejection rule into minimal space.

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 is not obligated to document return values, and the parameters are covered. The remaining gap is the absence of any tie-breaker against read_xml and no note on encoding or size limits, which an agent handling large or non-UTF-8 files would want.

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 for the two non-obvious parameters: offset is defined as a 1-based line number (critical, since the default of 1 could otherwise be misread) and limit as the maximum number of lines. Only 'path' is left unexplained, which is self-evident from the required-parameter 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 ('按行读取一个文本文件') and enumerates supported formats (xml/lua/txt/csv), so an agent immediately knows what this does. However, it never distinguishes itself from the sibling read_xml, which it even lists as a supported type, leaving a real routing ambiguity unresolved.

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 implied rather than stated: no explicit 'use this when' or 'use read_xml instead when' guidance is given, despite read_xml being an obvious alternative for part of this tool's format coverage. The one hard rule provided — that binary files are rejected — is a useful negative constraint but is really a behavioral trait, not selection 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?

With no annotations, the description carries the full burden. It usefully discloses output behavior (attributes flattened, same-name children merged into arrays, text under '_text') and the novel truncation behavior with max_nodes, which is not derivable from the schema. It omits error handling, encoding assumptions, and read-only 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?

Four terse lines, front-loaded with the core purpose followed by the mapping and truncation rules. Every sentence carries distinct information with 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?

An output schema exists, so return values need not be explained, yet the description adds useful structural detail anyway. Together with the max_nodes explanation and truncation semantics, the definition is sufficient for correct invocation; only error/encoding edge cases 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?

Schema description coverage is 0%, so the description must compensate. It explains max_nodes well ('限制节点总数，超出部分标记 _truncated'), clarifying both its meaning and its effect. The required 'path' parameter is left entirely to inference, though its meaning is self-evident.

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 ('把 XML 解析成嵌套字典返回' - parse XML into a nested dict) and even details the transformation mapping rules, so the purpose is unambiguous. It does not, however, explicitly distinguish itself from the sibling read_text, leaving that differentiation to inference.

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 guidance on when to use this tool versus alternatives such as read_text or search. The XML-specific nature implies a use case, but no explicit condition, prerequisite, or exclusion is stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses the default case-insensitivity, the regex interpretation mode, and the non-obvious translation-table reverse-lookup behavior (searching Chinese via $key). It does not mention permissions or rate limits, but for a read-only search these are minor.

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 main purpose is front-loaded in the first clause, followed by parameter behavior and return format. It is compact and each line adds information, though the multi-line layout is slightly dense.

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

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

Despite an output schema existing, the description still summarizes the return (files, line numbers, line content), and covers the key query semantics including the translation feature. The only gap, max_results, is minor for a search 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 coverage is 0%, so the description must compensate and largely does: it explains query (substring), regex, glob (with example patterns), and the default case-insensitivity that maps to case_sensitive. Only max_results is left undocumented, so nearly all parameters gain meaning.

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 ('在文本文件内容中搜索'), which is clearly distinct from reading (read_text/read_xml) or listing (list_dir). It is clear on its own but never explicitly differentiates itself from the sibling 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?

It explains how glob narrows scope with concrete examples and clarifies the regex toggle, implying when those options apply. However, it gives no explicit when-to-use/when-not guidance versus read_text or list_dir, leaving the agent to infer the choice.

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

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

With no annotations, the description carries the full burden, and it does disclose real traits: it parses source text only, never executes Lua, and deliberately makes no trade-offs, returning fields plus line-number ranges per version. That tells the agent the output is deterministic and raw. It still omits error behavior (e.g. unknown spell_id) and the meaning of the table cap.

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 clauses, purpose front-loaded, then the parsing constraint, then the follow-up routing. Every sentence earns its place with 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?

The output schema means return values need not be described, and the description adequately covers the parsing model and the hand-off to read_text. It remains incomplete on the undocumented max_tables parameter and on what happens when a spell id is absent or appears in fewer tables than the cap.

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 not name either parameter. spell_id is inferable from '把一个法术…的条目', but max_tables is never mentioned or explained, leaving the default-10 cap opaque.

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: it returns one spell's entries side-by-side across every version table in scripts/gun/gun_actions*.lua. That is far more precise than the bare name 'spell'. It does not, however, distinguish itself from the sibling tool spell_bundle, so an agent cannot tell the two apart from this text alone.

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 one clear routing rule: when the function body is needed, follow up with read_text on the reported line ranges. That is useful implied usage guidance, but there is no statement of when to prefer this over spell_bundle or entity, and no exclusion 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?

With no annotations, the description carries the whole burden and does so: it declares read-only, no Lua execution, no unit conversion, and discloses the automatic resolution steps (following related_projectiles, merging one <Base> layer, materials.xml particle colors, SpriteComponent atlas frames). It also names what is deliberately excluded (texture pixels, audio samples, engine formulas), which sets accurate expectations.

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 aggregation summary, then behavior/limits, then exclusions. No filler sentence; each line (auto-follow rules, read-only constraints, not_available contents) adds distinct, 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?

An output schema exists, so return-value documentation is not required, and the description covers aggregation semantics plus limitations well. The one shortfall is the missing explanation of what spell_id must be, which the agent needs before calling.

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 single parameter 'spell_id' is left completely undocumented. The description never says whether this is an internal ID, a name, a path, or its expected format, so it fails to compensate for the schema gap.

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 (一次性汇总 / one-shot aggregation) and resource (spell data), then enumerates exactly which sub-parts are bundled: card fields, projectile entity, effects, and sound. That scope makes it clearly distinguishable from the plain 'spell' 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?

Usage is only implied — the agent can infer this is the one-call way to get a full spell picture rather than chaining 'spell', 'entity' and 'read_xml'. There is no explicit when-to-use-this vs when-to-use-an-alternative routing, and no prerequisites named.

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

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

With no annotations, the description carries the full burden. It does disclose one genuine behavioral trait: when data/translations/*.csv is absent, available=False and reverse lookup by translation stops working while search still functions. That is useful degradation info, but permission needs, limit behavior, and result format are untouched.

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 tight sentences with the core behavior front-loaded and the data-source caveat following. No filler, though slightly more could have been said about the undocumented limit without harming brevity.

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 described, and the description still names the 'available' flag that appears in that output. Purpose, data source, and failure-mode behavior are covered; the only real gap is 'limit' and sibling routing.

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. It does add meaning for 'text' by explaining the input may be either a key or a translation, which the bare schema does not convey. The 'limit' parameter (default 20) is never explained anywhere, leaving half the parameters opaque.

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 operation on a specific resource: bidirectional lookup between a localization key and its translation. The reversal ('给 key 返回译文，给译文返回 key') is precisely stated, so an agent knows exactly what it does. It does not, however, distinguish itself from the sibling 'search' 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?

Usage is implied by the description ('查询本地化词条'), and the note about search remaining usable when the file is missing gives a partial operational condition. But there is no explicit when-to-use guidance and no routing against the sibling 'search' tool.

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