emulator_get_shader_stats

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

With no annotations, the description carries the full behavioral burden and discloses almost nothing: read-only vs. mutating is only implied by "Inspect", and there is no mention of whether the emulator must be running, whether the cache file is locked, or what happens if the v2 file is absent. The one useful hint is the concrete file name and the reference to legacy migration, but its effect on behavior is unexplained.

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?

It is a single front-loaded sentence with no filler, and the concrete cache file name is placed early. It is under-specified rather than verbose, which costs little on this dimension.

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 domain-specific cache-inspection tool with no annotations and no output schema, the description should explain what the returned statistics cover and what "legacy migration" means in practice. As written, an agent cannot tell what it will learn from calling this versus emulator_get_performance, leaving a significant gap.

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 100% and the single parameter emulator_dir is already documented as an optional base directory path, so the schema does the heavy lifting. The description adds nothing about how that path affects which cache file is inspected or what default is used, so baseline 3 applies.

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 names a concrete resource (Shader Cache v2, lichii-cache.v2.bin) and a specific verb ("Inspect"), which helps separate it from siblings like emulator_get_live_logs or emulator_get_performance. However, the tool name promises "stats" while the description lists records, pipelines, and legacy migration without saying what is actually measured or returned, so the core purpose stays fuzzy.

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?

There is no when-to-use guidance, no prerequisites (e.g. emulator must be stopped, cache file must exist), and no mention of when a sibling such as emulator_get_performance or emulator_get_rendering_defects would be the better choice. The agent must infer all routing decisions.

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