get_attendance_detail

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

Beyond the readOnly/idempotent/destructive annotations, it discloses the crucial interpretation rule that a date with no row means NOT POSTED and never absent, plus the auth-required prerequisite and the recovery sequence for NOT_AUTHENTICATED. These are genuine behavioral facts an agent cannot derive from annotations or schema.

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?

Purpose is front-loaded, followed by usage, then edge-case semantics, then auth. Each sentence carries information, though the density makes it slightly more crowded than necessary.

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 does explain the outcome values and the NOT POSTED convention, and it covers the auth prerequisite and cache behavior (via the refresh param, documented in the schema). It is complete enough to call the tool correctly, though it could say more about failure or error outcomes.

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 the schema already documents courseCode, date, refresh and semesterId in detail. The description largely restates the date-omission behavior the schema already states, adding only the NOT POSTED interpretation, so it does not meaningfully exceed the schema baseline.

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 names a specific resource and scope: per-class attendance for one course, returning every posted session with its date and outcome (Present / Absent / On Duty). This clearly distinguishes it from a coarse attendance summary. It does not explicitly name sibling tools like get_attendance or calculate_attendance, so it stops short of full sibling differentiation.

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?

It gives a concrete worked query ('was I present on 2026-10-12 in BCSE302L?'), states when to include the date versus omit it, and describes the NOT_AUTHENTICATED recovery flow (get_captcha then login then retry). What is missing is explicit routing against sibling attendance tools.

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