fill_from_weekly_schedule

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

With no annotations, the description carries the full behavioral burden and does well: it discloses dry_run default true for safety, on_name_conflict resolution modes, password requirement when returning to an existing name, and expansion/blocking semantics for buffer_minutes, block_efore, and block_after. It could add more about side effects on repeated calls, but key behaviors are covered.

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 structured with a concise summary line, a key matching note, and a flat args list. Every line adds information needed to invoke the tool correctly; no filler or repetition. Despite length, it earns its space for an 11-parameter tool.

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 complex, schema-poor, annotation-free tool, the description is nearly complete: it covers matching logic, all parameters, safety default, and conflict handling. Minor gaps remain around edge cases (e.g., overlapping busy blocks, exact suffix format for alternate_suffix), but an output schema exists and the essential invocation context is present.

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 0%, so the description must carry all parameter meaning. It does: all 11 parameters are individually explained with types, defaults, examples, and special values (e.g. on_name_conflict options, buffer, block_cutoffs, agent_name defaulting to env var). This exceeds what the sparse schema provides.

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: 'Fill a poll from recurring weekly busy blocks' and adds a clear use case ('best for class schedules'). It also distinguishes itself by noting it matches by weekday + local time and needs no week_start_date, cementing its unique role among 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?

The description clearly scopes usage to recurring weekly busy blocks and class schedules, and explains the matching mechanism (weekday + local time) rather than dates. It doesn't explicitly name sibling tools as alternatives or list when-not-o-use conditions, so it stops short of full exclusion guidance.

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