get_mod_tool

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

With no annotations provided, the description carries the full burden and does so well. It discloses that github and spacedock categories are lazily fetched, cached with specific TTLs (7 days and 3 days), and include fetched_at timestamps. It also states that force_refresh bypasses cache TTL, that not-found returns an error object, and that metadata includes is_cached when the ZIP is in the CKAN cache.

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 justifiably so given the empty schema. The opening is front-loaded with the core purpose, the Args section is scannable, and the bullet list provides necessary category details without redundant 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?

The description covers all three parameters, the exact identifier requirement, all available categories, cache and refresh behavior, error handling, and the special is_cached meaning. With an output schema already present, no further explanation of return values is needed.

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 document the parameters. It explains identifier as an exact CKAN identifier with examples, enumerates every category with its included fields, and clearly defines force_refresh. This is exemplary 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 'Get details for a KSP mod by its CKAN identifier', a specific verb, resource, and key distinction. It also contrasts with sibling search_mods_tool by telling agents to use that tool to find identifiers first, and with get_part_tool by clearly targeting mods.

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 description explicitly routes users to search_mods_tool to discover identifiers, which gives clear prerequisite guidance. The categories explanation helps agents choose what to request. It does not explicitly exclude alternatives like get_part_tool or list_tags_tool, but the main usage intent is unmistakable.

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