mureo_state_report_set

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

With no annotations, the description carries the full burden. It discloses key behavioral traits: atomic persistence, read-only dashboard usage, best-effort semantics, path restrictions, and return value. It does not contradict any annotations (none present). A score of 5 would require mentioning specific error handling or authorization needs, but the provided context is strong.

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 moderately long but efficiently structured. The first sentence immediately states the core purpose. Subsequent sentences logically cover report kind, summary structure, preservation behavior, best-effort note, and return value. Every sentence adds necessary context without redundancy. A 5 would require even tighter wording, but it is well-organized.

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?

Despite lacking an output schema, the description clearly states the return value ('updated state document'). It thoroughly explains the summary object, including nested flag conventions. For a state persistence tool with moderate complexity (3 params, nested object, enum), it provides comprehensive guidance. Minor gaps include no explicit error behavior or versioning, but overall it is complete enough for reliable use.

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?

All 3 parameters have schema descriptions (100% coverage), but the description adds significant value beyond schema. It explains the summary field's free-form nature and detailed conventions (e.g., ISO 8601 timestamps, flag structure, code vocabulary). This clarifies how to properly use the summary object, which is not fully captured in the schema alone. The path parameter's default and restriction are also reinforced. These additions warrant a 4.

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 the tool's purpose with specific verb ('persist') and resource ('structured analysis report summary into STATE.json's reports section'). It also explains the downstream use case (read-only dashboard rendering) and distinguishes from siblings by focusing on reports, not other state updates. The purpose is well-defined and actionable.

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 includes when to use (to persist report summaries for dashboard), how to use (selecting report kind and providing summary object), and a best-effort instruction to skip if MCP unavailable. It also mentions that other report kinds are preserved, implying additive behavior. However, it does not explicitly mention alternatives or when not to use compared to other state tools, which would push it to a 5.

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