aegis_create_rule

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces this counterintuitively ('it writes nothing to disk'), which is genuinely useful given the `create_rule` name implies a write. It also discloses the backtracking behavior of pulling in 'up to three active workspace rules (500 chars each) as examples' and assigns the actual file write to the agent, split responsibilities the annotations alone would not convey.

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, each carrying distinct information: what it produces, the no-disk-write caveat, and the save/check workflow. The npm package name and path templates make the middle portion dense, but nothing is redundant; the key point that it merely builds a prompt is front-loaded.

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 3-parameter, non-mutating tool with 100% schema coverage and no output schema, the description covers the essentials: input basis, example-injection behavior, and the manual save step. The one gap is what the returned 'instruction' actually contains, but the reference to `instruction` in the save step gives the agent enough to act.

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. The description exceeds that by explaining how parameters shape the output — the example budget of three rules at 500 chars each and the fact that `domain` and `rule_type` are hints fed into the draft prompt — which the schema only labels generically.

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 states a specific verb and resource: it 'builds a prompt for drafting a rule' from the `description` parameter, and explicitly clarifies it writes nothing to disk despite the name `create_rule`. It does not directly contrast itself with `aegis_capture_insight` or `aegis_scan`, but the prompt-building framing is distinct enough to separate it from the other siblings.

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?

It gives an explicit precondition — 'Check `aegis_list_rules` for an existing rule first' — naming the sibling that should be consulted, and describes the follow-up step of saving the result to `.aegis/rules/<type_dir>/<id>.md`. What's missing is guidance on when this tool is inappropriate or how it differs from `aegis_capture_insight`, which also produces rule-like content.

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