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

Goes well beyond the annotations: it discloses upsert semantics (same wording updates rather than duplicates), the idempotency_key retry contract, that the response returns the worker's rules with ids, and that this is an owner-level change that notifies the owner via Sergio. That owner-notification trait is exactly the kind of side effect annotations cannot 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?

Front-loaded with purpose and examples, then behavior, then alternatives, then a closing note on the owner notice. The hardness sentence is compressed into a parenthetical that reads slightly telegraphically, but no sentence is filler.

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?

With no output schema, the description still tells the agent what comes back (the rules with ids), and it covers idempotent retries, update-vs-create, removal, and the ownership side effect. Minor gaps remain around failure modes (e.g., ambiguous or unparseable plain-English wording) and permission requirements.

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 only 40%, and the description fills the biggest hole by defining what hard vs soft mean ("never scheduled against it" vs "avoided when possible") and noting hard is the default. It also clarifies staff_id scope and retry reuse of idempotency_key, though it says nothing about the reason parameter beyond what the schema already documents.

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 verb and resource ("Adds a plain-English scheduling rule for one field worker") and anchors it to the UI action ("as Add rule on their Rules tab does") with two concrete example rules. It is instantly distinguishable from set_staff_availability or set_staff_weekly_hours because it is plain-English rule text, not structured hours.

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?

Explicitly routes the agent to siblings: remove_staff_scheduling_rule for deletion and read staff_scheduling_rules for reading. It also implies the update path ("The same wording again updates the same rule"). It does not say when a rule should be expressed as a scheduling rule versus availability or weekly hours, which is the one remaining ambiguity.

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