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

Goes well beyond the annotations: discloses that this writes to VTOP, that the previewToken is server-signed, single-use and expires after 10 minutes, that a changed field invalidates it, and that login is required. The annotations (readOnlyHint=false, idempotentHint=false) are consistent with this and the description adds the full write-token lifecycle the agent cannot infer elsewhere.

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 critical fact (this writes and creates a real request), then organised as Call 1 / Call 2 followed by enforced rules. Sentences are dense but each carries an operational fact; there is 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 output schema, the description still describes what the preview returns (normalised values, fired rules, missed classes, previewToken) and the failure mode on a stale token. For a high-stakes write tool needing auth and human confirmation, nothing essential 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 already 100%, so the baseline is 3; the description still adds value by stating rules not present in the schema, such as to-date not preceding from-date, and by summarising the OG1 18:00-inclusive cutoff and 150-char cap in prose. Most of the individual field detail (leave codes, time normalisation, token semantics) duplicates the schema, which keeps this from a 5.

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 ('Apply for hostel leave on VTOP') and immediately distinguishes itself from the sibling write path by declaring it creates a real request. An agent can tell it apart from cancel_leave, get_leave_status, and get_leave_history without opening any 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?

Explicitly spells out the two-call protocol (preview vs submit), when to use each, the requirement to show the user the preview and get agreement, and the rule to never set confirm=true on a first call. It also routes the agent to get_leave_types when the leave code is unknown.

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 establish readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the login requirement, the NOT_AUTHENTICATED error token and its recovery sequence, credential sourcing via VTOP_USERNAME/VTOP_PASSWORD, and the fact that projections use the timetable grid plus academic calendar (holidays, working Saturdays). No contradiction with the readOnlyHint.

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 purpose, then prerequisites, then the output contract. It is dense and long, and the long inventory of return-field names makes it feel encyclopedic, but with no output schema each of those field names is carrying needed payload, so the length is largely justified.

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-required-param, 7-parameter analytical tool with no output schema, the description supplies the missing return-value documentation (upcomingSessions, ifAttendAllPercent, maxSkippableInRange, plannedBunk, perDay), the auth lifecycle, and the deadline-projection mechanics. An agent has everything needed to call and interpret it.

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 already 100%, so the baseline is 3; the description earns an extra point by explaining cross-parameter semantics the schema does not — bunkDates requires untilDate, toTermEnd is an alternative to supplying untilDate, and the targetPercent default of 74 exists because VIT's 75% threshold rounds up from 74.x.

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?

Opens with a specific verb+resource pairing ('Attendance / bunk calculator') that instantly separates it from the sibling fetchers get_attendance and get_attendance_detail. It then enumerates the exact derived quantities it produces (current %, bunkBuffer, classesToRecover), so an agent knows this computes rather than retrieves.

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 names the key use case ('I'm at the line; if I skip today can I still make 75%?') and the parameter combination that serves it (untilDate or toTermEnd, plus bunkDates). It also states the prerequisite (requires login) and the exact recovery path when auth fails (NOT_AUTHENTICATED -> get_captcha -> login -> retry), including the env-var fallback.

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 flag destructive=true and idempotent=false, but the description adds substantial context beyond them: the two-step safety design, that the previewToken is bound to the exact leave id and caller, that an approved leave may lack a withdraw control, and that login is required. This is rich 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?

Well front-loaded with the write warning, then the call sequence, then the caution. It is on the long side and some token-binding detail repeats across description and schema, but nearly every sentence carries operational value.

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 what the preview returns (type, dates, approval status, withdraw-control availability, previewToken). Combined with annotations covering the mutation profile, an agent has everything needed to call this correctly.

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 schema itself already documents confirm's two-step semantics and the token's binding to leave id/caller. The description reinforces but largely repeats that, so the baseline 3 applies with no meaningful addition beyond the 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?

States a specific verb and resource — 'Withdraw a hostel leave application on VTOP' — and immediately distinguishes itself from the sibling apply_leave and the read-only get_leave_status. An agent can tell exactly what this does versus the other leave tools.

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 defines the two-call protocol, when to use each call (preview vs. confirm=true), what NOT to do ('Never invent a previewToken or set confirm=true on a first call'), and the user-agreement prerequisite. Alternatives and exclusions are named directly.

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 safety (readOnly, idempotent, non-destructive), and the description adds substantial extra context: a 60-second cache with a bypass flag, a login requirement, an explicit no-retest rule, and a failure mode where an unreadable calendar yields nulls plus calendarAvailable=false rather than zeros. That is well beyond what the annotations 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?

Purpose is front-loaded in the first sentence, but the body is long and repetitive, re-deriving pass arithmetic (20/50, 6 of 15, 40/100, 12 of 30) and restating the canonical answer. Since the tool computes the result, much of this domain detail and the scripted user-facing phrasing could be trimmed without losing invocation guidance.

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 usefully explains two key output fields and their semantics (teeRequiredRaw as the answer, totalIfTeeClearedAtMinimum as an outcome), plus null-handling. It still omits the overall response shape (per-subject structure, other fields), but is largely complete for a complex domain 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 coverage is 100%, so both parameters are already documented, and the description's line 'semesterId is optional; omit for current semester' merely repeats the schema. The refresh/cache framing adds a little interpretive value but no syntax or format detail beyond the schema, so the baseline of 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?

The description states a specific verb and outcome ('Answer "will I pass this course?" for every subject') and anchors the scope to VIT Bhopal pass rules. It is clearly distinguishable from siblings like get_marks, get_internal_totals, and calculate_attendance, which return raw data rather than a pass verdict.

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 clear context (answering a pass/fail question with real rules) and even directs the agent to specific output fields for specific user questions ('READ teeRequiredRaw AS THE ANSWER'). It also warns against misusing totalIfTeeClearedAtMinimum. However, it never names an alternative tool or explicitly states when to use a sibling instead.

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, and the description redundantly confirms 'Read-only.' However, it adds genuinely new context the annotations lack: the tool requires login, and it discloses the exact shape of returned values (Submitted / Not Applicable / Not Submitted) along with the actionable interpretation of 'Not Submitted'.

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 short sentences, front-loaded with what the tool returns before the interpretation and the login prerequisite. Little waste; the parenthetical document examples are useful rather than padding, though 'Read-only' partly duplicates the annotation.

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 must carry the return-value burden and it does — it names the three status values and what a 'Not Submitted' entry means. The auth prerequisite is stated. Minor gaps remain around whether the list is scoped to the logged-in student only and whether it can be paginated or filtered.

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, which is the baseline-4 case; there are no parameter semantics to document or mis-document. The description correctly implies no filtering inputs are needed.

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 resource (admission/joining document checklist) and its exact scope: which VTOP documents are Submitted, Not Applicable, or Not Submitted. It enumerates the kinds of documents covered (mark lists, transfer/migration/conduct certificates, affidavits), so it is unmistakably distinct from siblings like get_fee_receipts or get_profile.

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?

Usage is implied rather than stated: the note that a 'Not Submitted' line is actionable tells the agent what the output means, but there is no explicit when-to-call or when-not-to-call guidance and no named alternative. For a no-param lookup with no close siblings this is adequate, not strong.

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 adds genuinely useful context: an auth requirement, an env-var credential fallback, and the explicit error-retry sequence. Caching behavior lives in the schema rather than here, which is a minor omission.

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, with the multi-step recovery instructions following. Dense and mostly waste-free, though the credential-fallback sentence is fairly long for an edge case.

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 describing the return shape (per-course attended/total/percentage). Auth prerequisites and the error path are covered; only pagination/cache specifics are left to the schema.

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 both parameters are already fully documented in the schema. The description only restates that semesterId is optional and defaults to the current semester, adding no syntax or format detail beyond the 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?

States a specific verb+resource and clarifies scope ('for all courses') plus the returned shape (attended/total/percentage per course), which implicitly separates it from get_attendance_detail and calculate_attendance. It never names those siblings, so differentiation is inferable rather than explicit.

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 workflow (on NOT_AUTHENTICATED call get_captcha then login then retry) and states that semesterId is optional and omitting it uses the current semester. It does not compare against the sibling attendance tools, so the agent must infer which tool to prefer.

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?

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.

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds substantive behavior beyond them: a login prerequisite, the NOT_AUTHENTICATED sentinel and its recovery chain, the term-scoped nature of festivals, and what the unfiltered default returns. These are non-obvious runtime traits 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?

Dense but front-loaded: resource and contents first, then per-filter usage, then recovery paths. Slight redundancy where the semesterId term-scoping explanation is repeated between description and schema, but every sentence carries operational value.

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 default return set and the NOT_AUTHENTICATED error sentinel. Combined with 100% schema coverage and annotations, an agent has everything needed to call this correctly.

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 per-parameter baseline is 3. The description goes further by explaining cross-parameter behavior not in the schema — the default result when no filter is supplied, and the term-scoping that governs query/semesterId — which genuinely aids correct 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?

The opening sentence names a specific resource (academic calendar) and enumerates its contents: holidays, events, working Saturdays/day-orders, and instructional days. It also names a sibling (get_semesters) for the term-scoping case, so the agent can distinguish it without opening other 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?

It explicitly maps each filter to an intent (query for a named event, month for a listing, holidaysOnly for no-class days, no filter for notable days) and gives a concrete fallback: if query finds nothing, call get_semesters and retry. It also prescribes the exact recovery path on NOT_AUTHENTICATED (get_captcha then login then retry).

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 say readOnlyHint=false, and the description explains exactly why: it saves the image to a file. It adds genuinely new behavioral context beyond annotations — a 30-60 second validity window tied to the next `login` call, plus structured failure modes (structuredContent.error.code such as RECAPTCHA_REQUIRED, CAPTCHA_NOT_FOUND) with an ordered recovery plan.

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 essential purpose and the critical 'don't guess' rule, and every sentence carries actionable weight. It runs long, but the length is justified by the anti-guessing safety warning and the error-code/recovery detail; no sentence 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?

There is no output schema, so the description carries the return-value burden and does so: it explains that the response contains an image plus a saved file and structured error codes. Combined with the timing and sequencing guidance, an agent has everything needed to call it correctly.

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 baseline is 4. The description usefully references a response field (`captchaFile`) the caller must consume, but does not elaborate further since there is nothing to document on the input side.

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 precise verb and resource ('fetch a CAPTCHA image from VTOP') and explicitly positions it as 'Step 1 of login', making its role in the flow unambiguous. It also discloses the side effect of saving the image to a file, so an agent can distinguish it from the sibling `login` and other read-only getters.

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 (immediately before `login`), what to do instead when the image isn't readable (open `captchaFile` or ask the user), and a hard prohibition ('never invent the characters', 'do NOT guess'). It even names the consequence of misuse (counts as a real failed login).

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real context beyond that: it requires login, and it queries the programme catalogue rather than the caller's enrolment records, which shapes expectations about which courses can be returned.

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 short sentences, front-loaded with the purpose, then input forms, then scope caveat, then auth note. No filler and nothing repeated.

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 return burden and does so: basket name, credits and completion state are all named. Input forms, scope (catalogue not personal records) and login requirement are covered, leaving nothing an agent needs 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 single parameter is already exemplified there, so the baseline is 3. The description adds genuine meaning: a title fragment matches potentially many catalogue courses, so 'get back every matching catalogue course' clarifies the partial-match, multi-result nature of the lookup rather than the one-code-one-result assumption.

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?

Opens with a specific verb+resource ('Which curriculum basket a course belongs to') and immediately illustrates both accepted input forms. A reader can distinguish it from the plural sibling get_curriculum_baskets (which lists baskets) without opening either 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 when-to-use context: 'Works for courses you have never taken — it reads the programme catalogue, not your records,' which tells the agent this is catalogue lookup rather than a personal-record query. It does not, however, explicitly name the alternative tools (get_curriculum_baskets, get_curriculum_progress) or state when not to use it.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's 'Read-only' is redundant. It does add two things beyond the structured data: the authentication requirement ('Requires login') and the data-provenance caveat that vtopMarkedCompleted is VTOP's own marking reported verbatim, which prevents the agent from treating it as a computed value.

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 what the tool returns, then the routing alternative, then two short operational flags. The field enumeration in sentence one is long but earned, since there is no output schema to document the return shape. No filler or restated platitudes.

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 describing returns and it does so concretely, plus it flags the login prerequisite. It stops short of mentioning pagination, volume, or failure behaviour, which an agent calling a full programme-wide curriculum query would benefit from knowing.

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 there is nothing for the description to disambiguate; baseline 4 applies. The description instead spends its budget on describing the returned shape, which is the right trade for a parameterless query tool.

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 resource ('Programme curriculum baskets') and enumerates exactly what each category/course row contains (code, title, type, version, L/T/P/J, credits), so the agent knows precisely what comes back. It distinguishes itself from one near-neighbour by naming get_pending_subjects, but never addresses the confusingly similar sibling get_course_basket, which is the most likely source of mis-selection.

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 routing guidance: use get_pending_subjects when you want completed-vs-left rather than the raw baskets. That gives a clear condition plus an alternative. It does not, however, tell the agent when to prefer this over get_course_basket, leaving the closest sibling unresolved.

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 safety profile is covered. The description adds genuinely useful behavior beyond that: the NOT_AUTHENTICATED → get_captcha → login → retry sequence, the fact that login auto-uses VTOP_USERNAME/VTOP_PASSWORD, and the fallback of asking the user for credentials. It omits return-format/pagination detail, but the enumerated fields largely cover that.

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 returned data, then the auth fallback chain. Every sentence carries operational weight (what it returns, auth requirement, recovery steps), though the auth instructions are dense enough that the description runs long for a read 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?

With no output schema, the description compensates by listing the returned fields, and it fully covers the auth prerequisite and failure handling. Nothing an agent needs to invoke it correctly is missing, aside from minor detail on pagination or empty-result behavior.

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 both parameters (refresh, semesterId) are already fully documented in the schema, including cache behavior. The description's note that semesterId is optional and omitted for the current semester only echoes the schema, 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 exam schedule) and enumerates exactly what it returns: CAT1/CAT2/FAT dates, timings, venues, seat numbers, row/col. This is clearly distinguishable from sibling read tools like get_marks, get_timetable, and get_semester_grades.

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 conditions: 'semesterId is optional; omit for current semester' and 'Requires login,' plus an explicit recovery path when auth fails. It doesn't name alternative tools for overlapping needs, but for a single-purpose lookup the when-to-use guidance is otherwise clear.

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, but the description adds real context beyond them: it requires login, amounts are as printed, and no currency conversion applies. A useful addition to an otherwise well-annotated read tool.

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 usage, then caveats. Tight overall, though 'Read-only.' slightly duplicates the readOnlyHint annotation.

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-param read tool with no output schema, the description compensates by naming the returned fields and the auth requirement. Complete enough to call correctly.

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 receiptNo including its 'omit for full list' semantics. The description restates but adds little beyond what the schema provides, so the 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 resource (fee payment receipts) and enumerates the exact fields returned (receipt number, date, amount, campus). No sibling tool covers fee receipts, so the agent can select it unambiguously.

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 describes the two modes: omit receiptNo for the full list, pass it to get a single receipt's detail breakdown. This gives clear conditional usage, though there are no true alternatives to steer away from.

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?

Despite annotations already covering the read-only/idempotent profile, the description adds substantial behavior: it explains that VTOP omits unpublished components rather than zeroing them, that 'outstanding' does not mean unconducted, that attendanceForecast is a projection paid only after the last instructional day, that grades are relative to class average, and that login is required. This is exactly the kind of domain-specific caveat 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?

The content is dense and front-loaded on the totals concept, but the ordering directive and the inline component arithmetic (40 = 35+5, CAT-I 15 + CAT-II 15, etc.) make it longer than necessary and push operational caveats into a single run-on block. It is information-rich but not tightly structured.

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 return-value burden and does so thoroughly, defining scoredSoFar, percentOfScale, outstanding, and attendanceForecast and explaining the edge cases behind them. An agent has enough to interpret the response and to call the tool correctly with no required parameters.

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 both parameters are already documented in structured form. The description restates that semesterId is optional and defaults to the current semester, which duplicates the schema rather than adding syntax or format 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?

The description opens with a specific verb+resource ('TOTAL internal marks for every subject') and pins down the aggregation being performed, which separates it conceptually from raw-mark siblings like get_marks. However, it never names or explicitly differentiates itself from get_marks or get_semester_grades, so the agent must infer which sibling to prefer from context alone.

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?

Usage is only implied: the reader learns the tool returns totals and should order output a certain way, and that semesterId may be omitted. There is no statement of when to call this versus get_marks or get_semester_grades, and no when-not conditions. The 'refresh' trigger lives in the schema, not the description.

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 two pieces of non-obvious context: statuses are reported verbatim as VTOP prints them (no normalization) and that authentication is required. It does not discuss result size or pagination for a full-history tool.

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 scope, followed by the field enumeration, usage triggers, and the status/login caveats. Dense but every element earns its place; the long field list is slightly padded but serves as a return-value preview absent an output schema.

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 and no output schema, the description compensates by naming the returned fields, the exact status representation, the auth requirement, and the sibling boundary. An agent has everything needed to select and call it correctly.

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 baseline is 4 and there is nothing to disambiguate. The field list in the description describes outputs, not inputs, which is fine and not counted against it.

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 ('Full hostel leave history') and enumerates the record fields returned (id, type, place, reason, from/to, status, approver remarks, gate-pass state). It explicitly distinguishes itself from the sibling get_leave_status, so an agent can route without opening either 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 concrete triggers ('what leaves have I taken?', past-leave questions) and names the alternative tool plus the condition that selects it (get_leave_status for current state). This is explicit when-to-use/when-not guidance.

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 and idempotentHint, so the description's 'Read-only' adds little. It does add valuable behavioral context: 'Requires login' and the caveat that gate-pass flags are only present 'where VTOP publishes them,' disclosing nullable 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?

A single well-structured sentence lists fields and ends with read-only and auth notes. Front-loaded with the core purpose and no wasted words.

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 describing returns and does so thoroughly, including verbatim status values and conditional gate-pass fields. It lacks explicit routing to alternatives, but is otherwise complete for a no-arg read 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?

Zero parameters, so baseline is 4. The description correctly documents that no input is required and instead details the return shape, which is the relevant information for a no-arg tool.

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 hostel leave applications + approval status) and enumerates exactly what fields are returned. It is clearly distinguishable from siblings like get_leave_history and apply_leave.

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 implies it returns current leave applications with status, which positions it against get_leave_history and get_leave_type_rules, but it never explicitly states when to use this versus those alternatives. Usage is only weakly implied.

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 reinforces them with a concrete guarantee ('this never submits a leave application'). It adds genuinely new context beyond annotations: the call mimics the dropdown's network request, and the return is unstructured raw text ('e.g. HOME TURN caps at 14 days'), which tells the agent to expect unparsed output.

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 'Diagnostic:' so the agent's role for the call is immediately clear, and each sentence carries distinct information (purpose, safety, rationale, return shape). Slightly padded by the parenthetical example and the 'read directly rather than guessed' flourish, but no dead weight.

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 one optional param, no output schema, and rich annotations, the description covers the key unknowns: it discloses that the output is raw unparsed text and why the tool exists. Remaining gaps are minor — no guidance on error/throttling behavior when probing all types at once.

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 lists the codes and the 'Omit for all' behavior, so the description's 'Omit leaveCode to probe every type' is largely a restatement. It frames the parameter's intent (probing) but adds no format, syntax, or failure semantics beyond the 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?

States a specific verb ('ask VTOP what rules apply') and resource (hostel leave-type rules: max days, limits, required fields), plus the mechanism (replays the dropdown request). It is clearly distinguishable from siblings like get_leave_types, apply_leave, and get_leave_history, which an agent can separate without opening any 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?

Explains when to reach for it ('day limits are server-side rules otherwise only discoverable by submitting and being rejected') and gives the probe-all case ('Omit leaveCode to probe every type'). It implies the alternative (apply_leave) but never names it explicitly or states a when-not condition.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds genuinely useful behavior beyond that: the output is read from the live form (so it is not a static enum), that labels are unsafe to submit, and that login is required, which is not captured by openWorldHint alone.

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 first sentence is well front-loaded, but the leave-form caveat is embedded mid-clause and the unrelated 6 PM in-time rule plus login note are bolted on, making the payload feel like three loosely related facts rather than one tight definition. Every clause is arguably useful, but the structure is not clean.

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?

Because there is no output schema, the description carries the burden of telling the agent what comes back, and it does so for the critical field (code vs label) and the login prerequisite. It is slightly over-stuffed with unrelated policy (6 PM rule) that is already its own sibling-ish concern, but an agent has enough to call and consume it correctly.

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 has zero parameters, so the schema defines nothing to document. The description appropriately uses the space to explain how to interpret the returned data (use the code, not the label), which is the only semantic question a caller of a zero-arg list tool could have.

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 (hostel leave types) and adds critical scoping detail that the values come from the live form rather than a cached assumption. Distinguishable from the sibling get_leave_type_rules, which presumably covers policy rather than the enumeration of types.

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?

Implies this is the lookup step before apply_leave by instructing 'Use the CODE, not the label', which tells the agent how to consume the result. It does not explicitly name apply_leave or get_leave_type_rules as the downstream/alternative tool, so full sibling routing is missing.

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), so the bar is lower. The description adds genuinely new behavior: it requires login and tells the agent to follow the error's `recovery` array on NOT_AUTHENTICATED. It stops short of explaining pagination or the shape of the recovery flow, keeping it at a strong 4.

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, then the alternative, then optional-param and error-handling notes. Every sentence carries information, though the dense field enumeration is slightly heavy. No filler or repetition.

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, yet the description thoroughly describes the return fields, the auth requirement, and the error-recovery path. For a two-param read tool whose annotations already carry the safety profile, nothing an agent needs to invoke it 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 description coverage is 100%, so both parameters are already fully documented, including the cache-bypass semantics of `refresh` and the format of `semesterId`. The description's 'semesterId is optional; omit for current semester' merely restates the schema, adding no new syntax or constraints. 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 enumerates the exact fields returned per component (raw marks, max marks, weightage, class average, status). It explicitly distinguishes itself from the sibling get_internal_totals, so an agent can route correctly without opening either 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?

Names the alternative (get_internal_totals) and the exact condition that selects it ('when you want the TOTAL for each subject rather than the component breakdown'). It also gives guidance on the optional semesterId and what to do on a NOT_AUTHENTICATED response.

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 read-only/idempotent/non-destructive, so the bar is lower; the description still adds auth context ('Requires login'), the rule that disagreements are surfaced in discrepancies rather than silently resolved, and the elective N-of-M completion model. 'Read-only' merely restates the annotation, but the discrepancy and derivation semantics are genuine added value.

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 meaning ('Subjects still to complete:') before the dense computation rules. Sentences carry distinct semantic load, though the em-dash-heavy style packs several rules into long clauses.

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 must characterize the return payload, and it does: names and credits, category totals showing how far short, VTOP's own row marking, and a discrepancies section. An agent knows both what triggers the tool and what comes back.

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?

Zero parameters, so there is nothing to document and the schema is trivially sufficient. Baseline of 4 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 resource and scope: the curriculum basket courses still outstanding after grade-history passes are subtracted. An agent can tell it computes pending status rather than a raw listing like get_curriculum_baskets or get_grade_history, though it never names those siblings explicitly.

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?

Usage is implied by the name and the phrase 'Subjects still to complete' — reach for it when you need outstanding requirements. There is no explicit when/when-not statement and no named alternative to route between against get_curriculum_progress or get_course_basket.

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 the safety profile is covered. The description adds value beyond that by disclosing the login prerequisite, which the annotations do not capture, though it does not describe pagination, error behavior, or freshness of the data.

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 field inventory is front-loaded and the two trailing sentences (read-only, requires login) are short and relevant. The field enumeration is somewhat list-like but earns its place given there is no output schema.

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 no parameters, the description carries the full burden and does so by enumerating the returned fields. It also covers the auth and read-only traits, so nothing needed to invoke this tool 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless tool is 4. The description's field list describes output, not inputs, which is appropriate here.

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 (proctor contact details) and enumerates exactly what is returned: faculty id, name, designation, school, department, cabin, email, intercom, mobile. It also distinguishes itself from the sibling get_student_profile by clarifying it exposes the same proctor data via the standalone proctor page, so an agent can choose between them.

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 mention that this is the same data as the proctor section of get_student_profile implies an alternative route, but it never states an explicit when-to-use rule or preference between the two. Usage is inferable rather than prescribed.

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 cover read-only/idempotent/non-destructive, and the description goes well beyond them: it pre-empts a false reading of `gpa: null` as zero during in-progress semesters, states login is required, and prescribes the NOT_AUTHENTICATED `recovery` retry path. This is exactly the extra context annotations cannot carry.

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, then layers the important gotcha and the auth-recovery note as short, high-value sentences. Dense but every clause carries operational meaning, with only mild redundancy around semesterId's optionality.

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 describing returns and does so for the non-obvious case (published:false, gpa:null, explanatory message), plus auth and cache behavior. An agent has what it needs to call and interpret this correctly.

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 both parameters are already documented at the field level; the description's note that semesterId is optional and defaults to the current semester largely repeats the schema. The `refresh` cache-bypass parameter is not mentioned at all, so no value is added there.

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 grades) scoped to a specific semester, and enumerates the content (course-wise letter grades + GPA). That scoping distinguishes it from siblings like get_marks and get_grade_history without needing to name them.

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 operating conditions: semesterId is optional and omitted means current semester, and in-progress semesters are called out with expected output. It never names an alternative (e.g. get_grade_history for cumulative records), so the 'use this instead of X' dimension 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?

Beyond the read-only/idempotent annotations, it discloses the important domain behavior that when teachingOver is true attendance is locked/final rather than projectable, and that login is required. This is non-obvious semantic context an agent cannot get 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?

Field list is front-loaded, followed by the teachingOver caveat and usage questions. Three sentences that each carry information, with no filler. Slight redundancy in restating return fields, but efficient overall.

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?

There is no output schema, so the description carries the burden of describing return values, and it does so thoroughly (all fields listed plus the locking semantics). Combined with the auth requirement note, 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 coverage is 100% and both parameters (refresh cache behavior, semesterId defaulting to current) are fully documented in the schema itself. The description adds no parameter-level detail beyond what the schema already provides, so the 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?

The description gives a specific resource (semester term bounds) and enumerates the exact fields returned: id, name, first/last instructional day, totals, days remaining, teaching-over flag. This is far more concrete than a tautology. It does not explicitly name how it differs from siblings like get_semesters or get_calendar, so it falls short of a 5.

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 explicit user-facing questions this answers ('when does my semester end?', 'how many teaching days are left?'), which is clear usage context. However it does not name the alternative tools (e.g. get_calendar or get_semesters) or state when-not to use it, so it does not reach 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?

Discloses non-obvious ordering: VTOP returns semesters newest-first, index 0 is current, index 1 is the most recent completed term, and the last element is the oldest. It also warns that taking the last element silently returns the student's first semester and documents structured error handling via structuredContent.error.code.

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 front-loaded with the tool's purpose, then immediately gives the critical ordering caveat, usage guidance, and error recovery. Every sentence provides operational value for correct invocation or interpretation.

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 no parameters, the description fully covers return contents, ordering, defaulting behavior of related tools, and authentication error recovery. An agent has enough information to call this correctly and interpret the result safely.

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 no input parameters, so the baseline is 4. The description appropriately does not invent parameter semantics, though it notes the response carries id and name.

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 list of available semesters', with output shape '(id + name)'. It also distinguishes its scope from other data tools that default to the current semester when semesterId is omitted.

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 most data tools default to the current semester, so 'you usually don't need to call this unless the user asks about a specific past semester.' It also gives a concrete recovery path for NOT_AUTHENTICATED errors.

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 materially beyond them: it warns the response is sensitive PII returned verbatim, instructs keeping it in the student's own session, states login is required, and documents the NOT_AUTHENTICATED recovery sequence plus credential handling. This is exactly the extra operational context annotations cannot carry.

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 purpose and the get_profile distinction, then privacy, then auth recovery — a sensible ordering. It is somewhat long, and the multi-step captcha/login/retry and env-var fallback detail is verbose for a no-arg reader, but each sentence carries actionable content.

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 returned sections and the field categories (DOB, addresses, board/school, parents, proctor contact, hostel block/room). Combined with the auth-requirement and recovery flow, an agent has everything needed to call and handle the tool correctly.

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 (empty schema, 100% coverage), so there is nothing to disambiguate and the baseline of 4 applies. No parameter meaning is present or needed.

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 (full student profile) and enumerates the exact content — the five accordion sections (personal, educational, family, proctor, hostel) with verbatim values. It also names what it excludes relative to the sibling get_profile (name/programme/branch/email/phone), so an agent can distinguish the two without opening a 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?

Explicitly routes the agent: 'Use this instead of get_profile when you need anything beyond name/programme/branch/email/phone', and lists the additional fields that justify the switch. It further specifies the auth recovery path (call get_captcha then login then retry on NOT_AUTHENTICATED) and the env-var/credential-prompt fallback, leaving nothing 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 cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new behavioral context: it requires login and prescribes a recovery procedure when the response contains NOT_AUTHENTICATED. It does not mention the 60-second cache at the description level (that detail lives in the refresh parameter schema), so it falls just short of the top mark.

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 purpose, then routing, then parameters, then auth guidance in a logical order. The sentence on the sessions array is somewhat detailed but justified because no output schema exists; overall density is high 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 explaining the response shape (courses, sessions array, duplicated multi-slot courses, top-level fields mirroring the first session), and it covers the auth failure path. Nothing an agent needs to call and interpret this tool 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 description coverage is 100%, including the caching rationale for `refresh`, so the schema already does the heavy lifting. The description only restates that semesterId is optional and defaults to the current semester, adding nothing beyond the 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?

Names a specific verb+resource ('Get class timetable') and enumerates the returned content (courses with slots, venues, faculty, credits, plus weekly sessions) at a level that lets an agent distinguish it from the other schedule-related 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?

Explicitly routes the agent: 'Use get_today_classes for "what do I have today"' and explains why (it applies the academic calendar and day-order overrides). It also states the semesterId default ('omit for current semester') and the login prerequisite.

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 only declare the safety profile (readOnly=false, openWorld=true, destructive=false). The description goes well beyond: env-var fallback semantics, the shape of failure output (structuredContent.error with code and needsUserInput), and the CREDENTIALS_REQUIRED captcha-reuse behavior. This is rich behavioral disclosure an agent could not 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?

Dense and front-loaded — the 'Step 2' framing and captcha requirement come first, followed by credential fallback and error handling. It is long but every sentence carries operational value; 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, yet the description explains the error return shape and recovery path, and covers the credential/config edge cases. An agent has everything needed to call this and handle failures correctly.

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. The description reinforces the optionality of username/password and adds a decision rule (only prompt the user when configuration is missing) plus captcha lifecycle details that the schema alone doesn't convey, nudging it above 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?

States a specific verb and resource ('Step 2 of login: submit credentials + the captcha'), and positions itself in a sequence relative to the get_captcha sibling ('the captcha you just OCR'd'). An agent can distinguish this from get_captcha and logout without opening any 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?

Explicit conditional guidance: omit credentials if env vars are configured, and only ask the user if the server reports they're not configured. It also names the alternative flow (fetch captcha via get_captcha) and instructs reuse over refetching. 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 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.

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

The description adds a fact the annotations do not carry: no authentication is required to call it, and it never mutates state. The read-only/no-change claim partially restates readOnlyHint and destructiveHint=false, but the 'does not require login' disclosure is genuinely new and useful for an agent deciding call order.

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 short sentences, front-loaded with the returned fields, then usage triggers, then the safety/auth caveat. Every sentence carries information and none repeats the title.

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, yet the description enumerates what is reported, which is exactly what the agent needs. The only gap is the undeclared `probe` parameter, which is not reflected in the schema and would need to be resolved elsewhere.

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?

With zero parameters the baseline is 4, but the description references a `probe: true` argument while the input schema declares an empty properties object. An agent following the description would attempt a parameter the schema does not expose, creating real ambiguity that offsets the otherwise clean no-param case.

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 (report) and enumerated resource elements: active session, registration number, credential configuration, and optional validity probe. It is immediately distinguishable from siblings like logout and login, which act on the session rather than report on it.

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 triggers: 'Call this before logging in if unsure' and 'when a data tool returns NOT_AUTHENTICATED.' It names the condition and the situation, leaving nothing to inference about when to reach for this instead of login.

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