Check For Updates

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

Annotations already convey read-only, open-world and idempotent behavior. The description adds genuine beyond-annotation context: a one-day result cache, a force override, and an environment-variable kill switch. It stops short of noting failure modes (e.g. offline/GitHub unavailable) but covers the key behaviors.

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?

Three sentences, front-loaded with purpose, then return contents, then caching/disable caveats. No wasted words; each sentence earns its place, though the caching and disable notes could be a single tighter clause.

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, yet the description enumerates the return payload (current and latest versions, update_available, update instructions). Combined with the caching and disabling behavior, an agent has everything needed to call and interpret this 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% and the single 'force' parameter is undocumented in the schema. The description partially compensates by implying force bypasses the day-long cache ('cached for a day unless force is true'), but never states the type or that it defaults to false, leaving semantics mostly implicit.

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+resource ('Check whether a newer ae-motion-mcp release exists') and names the mechanism (GitHub version tags). It is unmistakably distinct from all siblings, which are AE project-manipulation tools.

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?

Explains the operational context: default cached result, force to override, and that the tool is disabled when AE_MCP_UPDATE_CHECK=0. There is no meaningful alternative tool to route between, so the lack of explicit exclusions is not a real gap.

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