calculate_od

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

Adds substantial context beyond the annotations: it discloses that the tool makes several requests (per-course attendance detail), that the OD rule is unconfirmed and DSW-approved ODs cannot be distinguished, that a 'note' must always be surfaced, and it names the auth-failure token and recovery sequence. The annotations cover safety, but this description carries the real behavioral burden.

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 core purpose and the OD-limit caveat are front-loaded, followed by returns and the auth flow. It is dense but every sentence carries actionable information; only the parenthetical about DSW-approved ODs is slightly verbose.

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 compensates by enumerating the return payload (distinct OD days with dates, OD classes per course, days remaining, over-limit flag) and the mandatory 'note'. Combined with the auth-error handling, an agent has everything needed to call and interpret this tool.

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%, so courseCode and semesterId are already fully documented in the schema. The description implies per-course versus all-course aggregation ('OD classes per course') but adds no format or constraint detail beyond what the schema provides. Baseline 3 is appropriate.

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 ('Count your On-Duty (OD) days this semester') plus the data source ('per-class attendance detail') and the comparison it performs against the event-OD limit. This clearly separates it from the sibling calculate_attendance, which handles percentage-based attendance rather than OD day counting.

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 a concrete operating context: requires login, and an explicit recovery path (if NOT_AUTHENTICATED, call get_captcha then login then retry) that names the exact sibling tools to use. It does not, however, state when to prefer this over calculate_attendance or when OD counting is not applicable.

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