Lint event command lists

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

With no annotations, the description carries the full burden and does so thoroughly: it enumerates every rule with its severity class, discloses what is deliberately not checked ('Variable-designated transfers are not checked'), explains the approximate nature of maxLineChars, and reports output mechanics (sort order, 300-finding cap, truncated count, skippedMaps). This is behavioral context an agent could not get from any structured field.

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 and no sentence is filler; the rule catalogue and output mechanics all earn their place. It is a single dense paragraph, though, so the rule list would scan better as a structured block — a minor structural, not length, issue.

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?

No output schema exists, and the description compensates fully: findings carry {kind, mapId, eventId, page, index}, page/index are documented as 0-based with the troop-id convention for eventId, and truncation/counts/skippedMaps are all described. For a four-parameter read-only lint tool, nothing an agent needs to call it or interpret results is missing.

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%, so the baseline is 3, but the description genuinely adds: it clarifies that minSeverity's warning default suppresses info findings unless requested, that mapId only narrows the map portion of the scope, and it details exactly how maxLineChars is computed (control codes stripped, font-dependent approximation).

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: 'Statically checks event command lists in map events, common events and troop pages.' The scope is exact and it is distinguishable from sibling validators like validate_project or check_references, which are not described as linting event command lists with rule-level severities.

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 through defaults ('minSeverity defaults to warning, so info findings appear only when requested', 'scope defaults to all; mapId limits the map part to one map'), which tells the agent how to widen or narrow a run. However, it never explicitly says when to choose this over validate_project or check_references, nor does it state any exclusions, so the agent must infer the routing.

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