Archive: Fill Rate

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioural context beyond that: the output differs by input mode (time series vs cross-section capacity snapshot), which is the key trait an agent needs. It omits auth/prerequisite and precedence behaviour when both identifiers are supplied.

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?

Two sentences, front-loaded with the core resource and then the mode split; no filler. The opening fragment 'How full a section got' is slightly informal but still earns its place as the scope statement.

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?

An output schema exists and annotations cover the safety profile, so return-value detail is not needed here. The description is sufficient for the two primary call patterns, with only the edge cases (multiple optional params, term without CRN) left ambiguous.

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 0% with 3 undocumented optional params, so the description carries the full burden. It explains crn (quota time series for that term) and course_code (capacity vs enrolment over all past sections) and implies term pairs with CRN, but leaves 'term' and the conflict/precedence rules when multiple params are supplied undefined.

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 the resource concretely ('how full a section got') and enumerates the two operating modes keyed on CRN versus course code. An agent can tell this is a quota/enrolment-fill tool rather than a generic archive lookup, though it never explicitly contrasts itself with siblings like archive_grade_distribution or archive_term_sections.

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 clear mode-selection guidance: pass a CRN for a per-term quota time series, pass a course code for capacity-vs-enrolment across past sections. It also states the intent ('judge whether the course reliably fills up'), which tells the agent when the tool is the right one. No explicit exclusions or named alternatives, so it stops short of a 5.

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