beel_set_default_series

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds value beyond them: it discloses that the previous default is unmarked (a real side effect), that inactive series are rejected with 400, and that repeated calls change nothing. It doesn't cover permissions/auth requirements or the response shape, so it's strong but not exhaustive.

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 core action, then bullets the invariants, then the endpoint, then a clearly labeled 'Read before calling' block. Efficient and skimmable, though the guardrail cross-references and warning glyph add some length that isn't strictly needed for invocation.

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 mutation tool with annotations and no output schema, the description covers the mutation's side effects, failure mode (400 on inactive), idempotency, and prerequisite reading. Nothing critical to calling it correctly is missing; only return/permission details are absent, which are minor here.

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 description coverage is 100% – both company_id and series_id are thoroughly documented in the schema, including the note that company_id is the sole context source. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 precise verb+resource+scope: 'Marks an invoice series as the default of its document type for this company, and unmarks the previous one.' The side effect (unmarking the prior default) is stated up front, which distinguishes it from siblings like beel_ensure_default_series and beel_get_default_series.

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?

Gives concrete when-to-use context via constraints: only one default per type, the series must be active or the call is rejected with 400, and the call is idempotent. It also routes the caller to prerequisite resources (beel_rules_list, beel://guardrails/...). It stops short of explicitly naming alternatives such as beel_ensure_default_series or beel_patch_series, so it's clear but not fully routing.

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