kaeris_list_missing_keys

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

With no annotations, the description carries the full burden. It discloses what the tool returns (missing keys, missing values, extra, placeholder issues), notes that JSON works offline while other formats go through the backend '/api/parse' at no cost, and implies a read-only operation by listing keys rather than modifying files. It lacks explicit side-effect or permission information, but the read-only nature is strongly implied. This is solid disclosure for a list-type 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?

The description is well-structured: a lead purpose sentence, a brief note on formats/alternatives, then an 'Args' section and 'Returns' section. Every sentence provides value, and the most critical information is front-loaded. The length is justified by the need to document args and return shape, with no wasted words.

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 tool has 3 parameters (all explained in detail), no output schema (but the Returns section fully describes the response shape), and a moderately complex task (finding missing/placeholder-broken keys). The description also covers format compatibility and next-step alternatives, so an agent has all necessary context to select and invoke the tool correctly. No gaps are evident.

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 it does thoroughly. It explains 'source' with examples ('locales/en.json'), 'lang' with a code example ('de'), and 'out' including its default behavior and expected file naming ('<out>/<lang><source-ext>'). This adds meaning well beyond the bare schema fields, making the tool fully usable.

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 clearly states what the tool does: 'The exact keys missing or placeholder-broken in ONE target locale... so an agent knows exactly what to translate/fix.' It uses a specific verb ('list' implied) and resource, and distinguishes from translation tools by noting 'use kaeris_add_language or kaeris_translate to actually fill them in.' This is unambiguous and differentiates from siblings.

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 provides clear use context: to identify what needs translation/fixing. It explicitly names alternatives for the next step: 'use kaeris_add_language or kaeris_translate to actually fill them in.' However, it does not explicitly contrast with other sibling tools like kaeris_scan_repo or kaeris_list_languages, leaving some ambiguity about when to choose this over those. Still, the primary usage is well communicated.

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