get_part_tool

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 delivers: it discloses the partial-success behavior (formatted stats for supported modules plus a list of unsupported module names), and enumerates three specific failure modes returning an error object (mod not cached, ZP unreadable, part name not found). It stops short of explicitly stating this is a read-only operation, but 'Get' semantics strongly imply it.

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 longer than average, but it is organized into clear sections (summary, usage guidance, Args, Returns) and every sentence carries information. Minor redundancy: the cache constraint appears twice ('cached download ZP' in summary and 'local CKAN download cache' in usage). A small tightening would make it flawless, but structure is strong.

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

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

Given an output schema exists to cover return values, the description adds precisely the non-schema context an agent needs: the prerequisite cache condition, the correct calling sequence via list_parts_tool, full parameter semantics, and error-object behavior. For a 2-parameter read tool with no annotations, nothing critical is missing—an agent can invoke this correctly on first try without opening any other 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 fully compensate—and it does. The Args section explains both parameters beyond the schema: identifier gets a format example and the word 'Exact'; part_name gets a CFG-file source explanation, an example, the critical warning that it's the 'name' field not the display title, and a pointer to list_parts_tool. This is model-level parameter documentation.

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

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

The description opens with a specific verb+resource: 'Get full details for a single KSP part from a mod's cached download ZIP.' This clearly distinguishes it from siblings: list_parts_tool (lists parts), get_mod_tool (mod-level data), and search_mods_tool (search). The word 'single' and the mention of module-level stats make the scope 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?

Explicit routing is provided: 'Use list_parts_tool with detail="basic" first to get valid part names.' It also states the hard prerequisite—'Only works for mods present in the local CKAN download cache'—so an agent knows when the tool will fail. This is exactly the when/when-not guidance that helps an agent select correctly.

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