list_mod_configs

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

With no annotations present, the description carries the full burden — and it does add value by stating the returned fields (file path, mod ID, format, size), which tells a caller what to expect. Still, the description doesn't disclose anything about recursion depth, error behavior on bad directories, sorting, or whether this is a pure read (obvious for 'list' but not stated). Adding return-field semantics is useful, but the missing behavioral detail and absence of any mention of file count limits or permission requirements keeps it at the baseline.

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 sentences, minimal words, no filler or repetition. The core action is front-loaded ('List all mod config files...'), and the return contract follows immediately in the second sentence. Every word carries meaning without verbosity or redundancy.

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 straightforward read-only list tool with one well-documented parameter, the description covers both the input (config directory) and output (path, mod ID, format, size), which is the complete contract a caller needs. It misses only minor niceties like error behavior for invalid paths or what 'format' specifically refers to, but these are edge concerns that don't impede correct 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 coverage is 100% (single configDir parameter is described), meeting the baseline of 3. The description reinforces the parameter's purpose by defining the scope ('in a config directory'), but adds no additional semantic details about the parameter beyond that. The parameter is simple and adequately documented — no penalty, but the description doesn't exceed the schema's coverage.

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?

Uses a specific verb+resource combination: 'List all mod config files in a config directory (recursively)' — the 'all' + 'recursively' specifies scope beyond a simple list, and the returned fields (path, mod ID, format, size) clarify what is returned. It stands apart from siblings like find_orphaned_configs (different task) and read_mod_config (singular vs. collection), though it doesn't explicitly name the sibling it is not.

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 usage context is implied: an agent can infer this is the tool to call when it needs an inventory of config files before reading/validating them. However, there is no explicit statement of when NOT to use it or which sibling to choose instead, so the guidance is implicit in the purpose rather than spelled out.

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