rules

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

Adds real context beyond annotations: rules appear in full at the top of every start_here brief, are capped at 300 characters and 2,000 per project, and removal demands a verbatim user_request quote. It does not cover error behavior or what happens when the 2,000-rule cap is hit, so it falls short of a 5.

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?

Front-loads the definition of hard rules, then packs action semantics into tight parentheticals with zero filler. Dense but readable; the parenthetical action map is slightly cramped but every clause earns its place.

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?

Covers all three action paths for a 7-param mixed read/write tool with no output schema, including the write prerequisites. Minor gaps remain around include_removed semantics and failure modes, but nothing that would misroute an invocation.

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 71% (above baseline 3), yet the description still clarifies rule_id ('R<id> in the brief'), constrains user_request to the user's own words, and ties project to writes. It adds value over the schema, though include_removed and model are left to the schema alone.

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?

States a specific resource (a project's hard rules) with a concrete definition ('things never to do') and enumerates the three operations (list/add/remove) with verb-level clarity. An agent can distinguish this from siblings like start_here (which displays rules) or log_learning without opening the schema.

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?

Explicit routing conditions are given per action: add 'when the user states a rule', remove 'ONLY when the user asks you in this chat', and list is marked read. This is as close to when/when-not guidance as a multi-action tool gets.

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