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

Annotations cover the safe read-only profile, and the description goes well beyond them: it discloses the login requirement, the exact error-recovery sequence, credential sourcing (VTOP_USERNAME/VTOP_PASSWORD), and the fact that projections use the timetable grid plus academic calendar including holidays and working Saturdays. That is real behavioral context an agent needs before calling.

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 and the headline use case are front-loaded, and the long middle sentence is dense with return-field names rather than filler. It is somewhat verbose and repeats the login/targetPercent points that the schema also carries, costing a point.

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 fully carries the return-value burden: it enumerates upcomingSessions, ifAttendAllPercent, ifSkipAllPercent, maxSkippableInRange, mustAttendInRange, canBeSafeByDeadline, plannedBunk, and perDay. Authentication, defaults, and optional-parameter interactions are all covered.

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 100%, so the baseline is 3, but the description adds genuine meaning: it explains the targetPercent default rationale (74.x rounds to 75), that bunkDates requires untilDate, and frames the untilDate/bunkDates pairing as the primary use case rather than just restating field docs.

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 framing ('Attendance / bunk calculator') and enumerates exactly what it computes per course (current %, bunkBuffer, classesToRecover). It is clearly distinguished from the sibling get_attendance, which fetches raw data while this one computes projections.

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 names the 'key real use case' verbatim and gives the exact condition for passing untilDate and bunkDates ('I'm at the line; if I skip today can I still make 75%...'), including the instruction to ASK THE USER for the closing date. The authentication path (NOT_AUTHENTICATED -> get_captcha -> login -> retry, env var fallback) is spelled out explicitly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely useful behavior: it requires login and prescribes the exact recovery flow (get_captcha → login → retry) on NOT_AUTHENTICATED. It further explains that relative vs absolute grading is irrelevant because the grade→point mapping is fixed.

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-loaded with the core purpose and scale, followed by mode rules, so an agent gets the essentials immediately. It is dense and long, packing several parenthetical asides into one paragraph, but nearly every clause carries actionable information.

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 describing return values (current CGPA, percentage, total credits, per-semester GPA) and the auth failure path. For a 6-param tool with zero required params, the coverage of modes, params, and error handling is complete.

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 100%, so the schema documents every parameter and the baseline is 3. The description still adds value by spelling out parameter interactions—courses drives projection, targetCgpa pairs with plannedCredits, semesterId is used only when courses is omitted—and flags courses as the most reliable forecasting path.

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+resource (GPA/CGPA/percentage calculator) and pins down the exact scale and formula. It explicitly distinguishes itself from the sibling predict_grades by clarifying it works from already-awarded letter grades, so an agent can tell the two apart without opening schemas.

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 explicit mode-selection rules: no args → current CGPA; courses → what-if/projection; targetCgpa+plannedCredits → required GPA; semesterId → stored semester. It also names the alternative tool (predict_grades) and the condition that selects it, so nothing is left to inference.

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

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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description layers on the auth requirement, the exact error token to watch for, the ordered retry sequence, and how credentials are sourced. This is exactly the operational context an agent needs and cannot get from structured fields.

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 purpose and output shape, then appends the recovery procedure in a logical order with no filler sentences. It is dense in one block, but every clause carries information.

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 describing the returned per-course fields, and it fully covers the authentication failure path. Only minor gaps remain, such as whether other error states exist or whether results are cached.

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% and the single optional parameter is already documented in the schema. The description's note that semesterId is optional and defaults to the current semester restates the schema rather than adding new meaning, so the baseline 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 specific verb and resource ('Get attendance records for all courses') and even previews the payload shape (attended/total/percentage per course), so an agent knows exactly what it returns. It does not, however, differentiate itself from the sibling calculate_attendance, leaving ambiguity about which one to pick.

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?

Provides a concrete recovery path for the NOT_AUTHENTICATED case (get_captcha -> login -> retry) and explains the credential fallback to VTOP_USERNAME/VTOP_PASSWORD env vars, then to asking the user. It also clarifies that semesterId may be omitted. The gap is that it never says when to prefer this over calculate_attendance.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description adds substantial context beyond them: it requires login, discloses the NOT_AUTHENTICATED recovery flow, and explains the semester-scoping behavior of festivals (with a fallback to get_semesters). This is meaningful operational context an agent needs.

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-loaded with the core purpose, then the parameter guidance, then the fallback/auth caveats in priority order. It is information-dense and free of filler, though the long multi-clause sentences are slightly run-on.

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 still covers defaults, parameter intent, semester-scoping edge cases, and the auth error path. An agent has everything required to call it correctly and recover from the common failure modes.

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 100%, so the baseline is 3, but the description adds genuine semantic value: it explains the default behavior with no filter, how query/month/holidaysOnly differ in intent, and why semesterId may be needed to locate a term-bound event.

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 ('Look up the academic calendar') and enumerates exactly what it contains: holidays, events, working Saturdays/day-orders, and instructional days. This scope is clearly distinguishable from siblings like get_timetable or get_exam_schedule.

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?

Explicitly maps each parameter to an intent (query for named events, month for a month listing, holidaysOnly for no-class days) and describes the no-filter default. It also names concrete alternatives and recovery paths: get_semesters when a query finds nothing, and get_captcha/login on NOT_AUTHENTICATED.

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

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

Annotations cover the safety profile (destructiveHint=false, openWorldHint=true), so the bar is lower, yet the description adds real behavioral context: it returns an image intended for the model to OCR, and it discloses the credential/env-var dependency. It stops short of describing failure modes (e.g., what happens if OCR fails or the captcha expires), which a login-flow tool could reasonably include.

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?

Three sentences, front-loaded with the 'Step 1 of login' frame, and each sentence carries actionable instruction (what it returns, what to do next, when to involve the user). No filler.

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?

No output schema exists, and the description compensates by explaining the return value (an image for OCR) and the downstream handoff to `login`. For a parameterless, single-step tool this is complete.

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?

The tool takes zero parameters and the schema is empty, so there is nothing to disambiguate; baseline for 0 params is 4. No misleading parameter guidance is present.

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 (fetch) and resource (CAPTCHA image from VTOP), and frames it as 'Step 1 of login'. It distinguishes itself from the large sibling list (get_marks, login, etc.) by naming `login` as the required follow-up, so an agent knows exactly where this fits in the flow.

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?

Explicit when-to-use (step 1 of login), what to do immediately after (call `login` with the OCR'd text), and a clear negative instruction (do NOT ask the user to read the captcha). It even scopes when user credentials are needed. Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them by disclosing the authentication requirement, the exact NOT_AUTHENTICATED recovery chain (get_captcha → login → retry), and the VTOP_USERNAME/VTOP_PASSWORD env-var fallback. This is precisely the kind of operational context annotations cannot express.

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 and return contents are front-loaded, and the sentences each carry information (scope, example questions, auth recovery). The auth narrative is somewhat long and slightly run-on, but nothing is filler.

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 carries the burden of return-value disclosure and does so by enumerating the reported sections (credits, categories, baskets, CGPA, grade counts). Combined with the auth-failure 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?

The tool takes zero parameters, so the baseline of 4 applies and there is nothing param-level to disambiguate. The description correctly spends no space on inputs.

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?

Names a specific verb+resource (get degree progress) and enumerates exactly what is returned: credits earned vs required, per-category and per-basket breakdown, CGPA, and grade-letter counts. It is clearly distinguishable from siblings like get_curriculum_baskets or get_pending_subjects, which cover narrower slices.

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 user-question triggers ('how many credits left?', 'how close am I to graduating?', 'which baskets do I still need?') that make the intended use unambiguous. It does not name an alternative tool or state when NOT to use it, so it falls short of full when/when-not routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds real behavioral value by disclosing the login prerequisite, the NOT_AUTHENTICATED error contract, and the env-var credential fallback. It stops short of describing the response shape or behavior for an invalid semesterId.

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 what is returned, then the auth-recovery flow, then the parameter note — a logical order with no filler sentences. It is dense but slightly run-on, packing three separate auth steps into one sentence.

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 single-optional-parameter read tool with no output schema, the description covers the returned fields, the auth requirement, and the failure-recovery path. An agent has everything needed to call it correctly without inspecting other tools.

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 100% and the schema already documents semesterId including the 'omit for current semester' default. The description's 'semesterId is optional; omit for current semester' repeats the schema rather than adding format or validation detail, so the baseline 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?

Specific verb (get) plus resource (exam schedule) with an explicit enumeration of the payload: CAT1/CAT2/FAT dates, timings, venues, seat numbers, row/col. This clearly separates it from siblings like get_timetable, get_marks, and get_calendar.

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 recovery path when the response contains NOT_AUTHENTICATED (call get_captcha, then login, then retry) and explains the credential fallback. It does not, however, contrast this tool with near-neighbors such as get_timetable or get_calendar, so sibling selection is left to the purpose statement.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds genuinely new behavioral context: the auth prerequisite, the exact NOT_AUTHENTICATED sentinel in the response, the env vars login consumes, and the user-prompt fallback when credentials are missing. That is precisely the kind of auth and error-contract detail the annotations cannot convey.

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 purpose and returned payload are front-loaded in the first sentence, followed by the recovery procedure in priority order. The credential sentence is slightly dense but each sentence carries actionable instruction with no filler.

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 parameters, no output schema and a covered annotation set, the description compensates by describing the returned content itself and the full auth/retry loop. An agent has everything it needs to call this tool and recover from the expected failure.

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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics for the description to elaborate. It correctly avoids inventing arguments.

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 gives a specific verb and resource and then enumerates the returned scope (CGPA, total earned credits, per-semester GPA + courses + grades grouped by exam month), which implicitly separates it from siblings like get_semester_grades or get_marks. It stops short of naming an alternative explicitly, so it does not quite reach the top band.

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 provides strong conditional guidance for the failure path (NOT_AUTHENTICATED -> get_captcha -> login -> retry) and the credential fallback, and states the login prerequisite outright. It never says when to prefer this tool over get_semester_grades or get_marks, so selection guidance is inferred rather than stated.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds meaningful context: it discloses the NOT_AUTHENTICATED sentinel, the login prerequisite, the env-var credential fallback, and what to do if credentials are missing. It does not describe rate limits or detailed return structure, but far exceeds the annotation baseline.

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 authentication flow instructions are front-loaded and actionable, but the sentence structure is dense and repetitive—it explains 'login' behavior at length within a tool that primarily fetches marks. The core purpose is stated first, but roughly half the text is about authentication mechanics better suited to the login tool description.

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 single-param read tool with full schema coverage and no output schema, the description is sufficiently complete: it names the resource, the optional param behavior, and the auth recovery path. It could benefit from clarifying how this differs from sibling grade tools, but nothing essential to invocation is missing.

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 100%, so the schema fully documents semesterId including format and default behavior. The description merely restates that semesterId is optional and can be omitted for current semester, which aligns exactly with the schema description without adding new syntax or edge-case detail. 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 ('Get internal marks/assessment scores') and even enumerates the returned fields (component-wise marks, weightage, status). It distinguishes the resource from siblings like get_grade_history and get_semester_grades implicitly, but does not explicitly differentiate.

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?

Provides explicit when-to-use context for the auth-recovery flow (call get_captcha then login then retry on NOT_AUTHENTICATED), which routes the agent to specific alternatives. It also notes semesterId is optional and to omit for current semester. However, it does not differentiate this tool from grade-related siblings like get_grade_history.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds meaningful non-obvious behavior: the NOT_AUTHENTICATED recovery sequence and the credential-resolution order (env vars then user prompt). It doesn't cover pagination or error shapes, but the auth-recovery chain is the critical operational detail and it is fully disclosed.

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-loaded with the resource and its fields, then the recovery procedure. Every sentence carries operational weight. It is dense but not redundant; the auth instructions are necessarily multi-step and cannot be shortened without losing the retry chain.

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?

No output schema exists, so the description's field enumeration stands in for it and does so adequately. The auth prerequisite and recovery path are spelled out. Complete enough to call correctly; the only omission is the shape of the profile object beyond field names, which is minor for a simple profile fetch.

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?

The tool takes no parameters, so the schema has nothing to say; baseline is 4. The description correctly signals that no arguments are needed and instead spends its budget on the auth flow, which is the only variable that affects invocation.

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 (get) and resource (student profile), then enumerates exactly what fields are returned. Distinguishable from the sibling get_student_profile by name and scope, and the field list makes the return contract concrete.

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?

Explicitly says 'Requires login' and gives a full conditional playbook: on NOT_AUTHENTICATED, call get_captcha then login then retry. It even specifies the fallback when env credentials are missing (ask the user). This is a rare, complete when/when-not/alternative prescription.

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

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

Annotations already declare readOnly/idempotent/non-destructive and open-world, and the description adds substantial context beyond them: the NOT_AUTHENTICATED response contract, the get_captcha → login → retry sequence, and the env-var credential fallback with user-prompt escalation. This is rich, actionable behavioral disclosure.

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 is front-loaded in the first sentence, and the remaining sentences cover auth behavior that genuinely aids correct invocation. It is somewhat verbose with the auth flow spelled out inline, but each sentence carries information.

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 naming the return contents (course-wise grades + GPA) and the special NOT_AUTHENTICATED signal, and it fully covers the auth prerequisites and recovery. Nothing an agent needs to call this correctly is missing.

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 100% and the schema itself already documents semesterId including the 'omit for current semester' behavior. The description restates this ('semesterId is optional; omit for current semester') but adds no format syntax beyond the schema's example, so baseline 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 specific verb+resource with scope: 'Get grades for a specific semester (course-wise grades + GPA)'. An agent can tell this returns per-course grades plus GPA for one semester. However it does not distinguish itself from the very close siblings get_grade_history and calculate_gpa, leaving overlap to inference.

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?

Provides clear operational context ('semesterId is optional; omit for current semester', 'Requires login') and a full retry flow. But it never says when to prefer this over get_grade_history or calculate_gpa, so routing among siblings is left implicit.

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

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

Annotations only cover safety (read-only, idempotent, open-world, non-destructive). The description adds crucial behavioral context beyond that: authentication is required, NOT_AUTHENTICATED triggers a get_captcha → login → retry flow, and login can use environment variables or prompt for credentials. This is information an agent cannot infer from structured fields.

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 compact and front-loaded: first sentence states the purpose and return shape, second gives usage guidance, third and fourth handle the auth recovery flow. No sentence is wasted.

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?

Given this is a zero-parameter, read-only, idempotent tool with no output schema, the description covers everything an agent needs: what it returns, when to call it, and the full authentication error-handling path. It is complete for its complexity.

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?

There are zero parameters, so the baseline is 4. The description appropriately doesn't invent parameter details, and the absence of filtering options is clear from the empty schema.

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 states a specific verb and resource: 'Get list of available semesters (id + name)'. It also explains how this tool relates to sibling data tools by noting they default to the current semester, so an agent can tell it apart.

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 explicitly says when to use it ('unless the user asks about a specific past semester') and when it can be skipped ('usually don't need to call this'). It also provides a clear recovery workflow for NOT_AUTHENTICATED and missing credentials.

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

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

Annotations only declare safety traits (readOnly, idempotent, openWorld), but the description surfaces the real behavioral burden: the tool requires an authenticated session, can return a NOT_AUTHENTICATED sentinel, and defines the full retry/login choreography plus credential sourcing. This is meaningful context an agent cannot derive from the 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?

Front-loads what the tool returns, then the authentication handling, which is the right priority order. It is somewhat dense and reads as a run-on chain of imperatives ('get_captcha then login then retry this tool'), but every clause carries actionable information.

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 correctly enumerates the returned fields, and it fully covers the auth lifecycle and the sole optional parameter's default. An agent has everything needed to call the tool and recover from the primary failure mode.

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 100% and the schema itself documents semesterId, its example format, and the omit-for-current-default behavior. The description only restates 'semesterId is optional; omit for current semester,' adding no syntax or semantic value beyond the structured field, so baseline 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 specific verb ('Get') and resource ('class timetable/schedule') and enumerates the payload contents (courses, slots, venues, faculty, credits). This cleanly separates it from siblings like get_exam_schedule, get_today_classes, and get_calendar, which an agent could otherwise confuse with a general timetable call.

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 operational guidance: omit semesterId for the current semester, and the exact recovery sequence (get_captcha -> login -> retry) when NOT_AUTHENTICATED appears, including the env-var fallback and when to prompt the user. It does not explicitly contrast with sibling schedule tools such as get_today_classes, 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.

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

Adds substantial behavioral context beyond annotations: returns a holiday/no-class result on non-instructional days, follows working-Saturday day-order rules, and specifies the NOT_AUTHENTICATED recovery sequence (get_captcha → login → retry). These are non-obvious runtime behaviors an agent must know.

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 primary purpose, then layers calendar edge cases and auth recovery in a compact run of sentences. Slightly dense but every clause carries information; no filler.

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 single-param read tool with no output schema, the description covers purpose, edge cases (holidays, working Saturdays), auth failure handling, and parameter usage. Nothing an agent needs is missing.

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 100%, so the baseline is 3, but the description clarifies the format ('ISO YYYY-MM-DD') and adds the default behavior ('or a given date', 'today'), marginally enriching what the schema already states.

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 (list) and resource (classes scheduled for today) with scope qualifiers including time and venue. Distinguishes itself from the sibling get_timetable by being date-scoped ('today') rather than a general timetable.

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?

Clear context for when to use (today's classes, or another day via the date param) and explains the auth-recovery flow. Does not explicitly contrast with get_timetable, but the 'today' framing makes the intended use case obvious.

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

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

Annotations mark this as non-read-only and open-world, so the description does not need to establish that it mutates remote state. It adds real behavioral context beyond the annotations: server-side env-var credential fallback and a defined error path ('server reports they're not configured'). It stops short of describing what a successful login yields (session/token) or how a failed captcha is surfaced.

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?

Three tight sentences, front-loaded with the step identity and the required action, followed by the credential-optional rule. No filler or restatement of the tool name.

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 and a small, fully documented parameter set, the description covers the inputs and the credential-resolution behavior adequately. It leaves the return value and post-login session semantics unstated, which is a minor gap for an authentication 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 the schema already explains all three parameters, including the env-var fallback for username and password. The description adds only the cross-tool hint that the captcha comes from the OCR step, which is marginal beyond what the schema's 'Captcha solution from the get_captcha tool' already states.

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 ('submit credentials + the captcha') and explicitly frames itself as 'Step 2 of login', which cleanly separates it from the sibling get_captcha (step 1). An agent can identify the tool's role in the flow without opening the schema.

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 conditional guidance: omit credentials when VTOP_USERNAME/VTOP_PASSWORD are set on the server, and only prompt the user if the server reports they are missing. It does not address the re-login case (e.g., what to do if a session already exists), which is the one remaining when-to-use gap.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description adds the meaningful behavioral detail that the session is cleared, which is the key side effect. It stops short of stating auth requirements or that subsequent calls will fail, but this is solid added context beyond the annotations.

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?

A single short sentence front-loads the action and its effect. There is no filler or redundant restatement of the name.

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 zero-parameter, no-output-schema session tool, the definition covers what the tool does and its side effect. It could add a note that the session must exist or that later calls will fail, but nothing essential for invocation is missing.

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?

The tool takes zero parameters, so the schema-side burden is nil and the baseline of 4 applies. Nothing about parameters needs explaining.

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 (logout) and resource (VTOP session) with the added effect of clearing the session. It is clearly distinguishable from the many read-only siblings and from 'login', though it does not explicitly name a sibling to contrast with.

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 intent of 'logout' implies its own usage context, so an agent can infer when to call it. However, there is no explicit guidance about prerequisites (an active session) or what to expect if no session exists, and no alternatives are mentioned.

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