Deploy Custom Rule

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

Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes far beyond by disclosing that the tool writes to ~/.iris/custom-rules.json via atomic write, appends to audit log, activates immediately, persists across restarts, is not idempotent (mints fresh rule_id), is tenant-scoped, rate-limited to 20 req/min, and surfaces specific error modes (400, 429, 500). No contradiction with annotations.

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 long but every sentence earns its place. It is front-loaded with purpose, then differentiates siblings, explains behavior, output shape, usage guidance, parameter semantics, and error modes. The structure is logical and scannable, with no repetition or filler. For a tool with 6 parameters and nested objects, this complexity warrants the length.

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 is fully complete for a write-path tool with no output schema. It covers purpose, exact file write behavior, non-idempotency, tenant scoping, rate limits, output JSON shape, parameter semantics, when to use/avoid, and all error modes. Even without an output schema, the agent knows exactly what to expect and how to handle failures.

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?

Although schema coverage is 100%, the description adds substantial meaning: name length constraints and its appearance in eval_result rule_results, evalType must match evaluate_output eval_type with concrete examples, severity affects sorting/audit but not scoring, definition type/config pairing examples (regex_match needs config.pattern, cost_threshold needs config.max_cost, etc.), and invalid configs rejected at deploy time. This is far beyond the baseline.

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 opens with a specific verb+resource+scope: 'Deploy a new custom evaluation rule that will fire on every future evaluate_output call of its eval category.' It explicitly distinguishes from siblings by naming them (list_rules, delete_rule, evaluate_output, log_trace, get_traces, delete_trace, evaluate_with_llm_judge, verify_citations) and states deploy_rule is the 'WRITE path that grows the custom-rule library.' This is unambiguous and clearly differentiated.

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 gives explicit when-to-use guidance: 'Use when an agent observes a recurring failure pattern and decides to enforce it as a standing rule.' It also gives explicit when-not-to-use guidance: don't use to validate (use the preview endpoint) and don't use to edit (use delete_rule + deploy_rule). It further maps a concrete workflow combining evaluate_output + get_traces + deploy_rule. Alternatives are explicitly named and contextually placed.

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