mock_rule_write

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

With no annotations provided, the description must carry the full behavioral load. It correctly states the write (mutation) nature and the key constraint that fixture rules need fixture_json or fixture_text unless a fixture already exists. However, it does not disclose other important behaviors like overwrite semantics, error handling, or side effects.

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 compact and front-loaded with the action and alternative preference, followed by the shape and fixture notes. Every sentence adds value, though the shape definition could be slightly more structured, but overall it is efficient.

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 description covers the rule structure and fixture requirements, and an output schema exists for return values. It omits edge-case behaviors like whether the write overwrites existing rules, but given the 'advanced' label and the presence of an output schema, it is reasonably complete for an experienced agent.

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?

The schema has 0% description coverage and the 'rule' parameter is an unconstrained object (additionalProperties true), so the description is essential. It provides a detailed shape for the rule and explains when fixture_json and fixture_text are needed, significantly compensating for the sparse schema.

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 verb 'Write' and the resource 'rule document', and it explicitly recommends the alternative mock_rule_create_from_entry, which differentiates it from that sibling. The term 'directly' hints at a lower-level operation, but the core purpose is unambiguous.

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 explicitly names the preferred alternative (mock_rule_create_from_entry) and says to prefer it, providing clear 'when-not-to-use' guidance. However, it does not state explicit conditions under which this advanced tool should be chosen, leaving that partially to inference.

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