itu-mcp

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 usefully discloses the analysis dimensions produced, but says nothing about term validity requirements, error behavior, or whether courses missing from a term are omitted or flagged.

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?

One dense sentence that front-loads the core action ('Diff one course's sections between two archived terms') before listing the metrics. It is slightly clause-heavy but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the compared dimensions are stated. However, with three undocumented parameters and no term-format or ordering conventions, an agent still lacks enough to construct a correct call confidently.

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 0% and all three parameters (course_code, term_a, term_b) are only bare strings in the schema. The description does not specify term code format, whether term_a must be the earlier term, or the course_code convention — so the description fails to compensate for the coverage gap.

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 (diff/compare) and resource (one course's sections across two archived terms), and enumerates the dimensions compared (instructor turnover, section-count delta, capacity/fill movement). It also distinguishes itself from the sibling archive_term_sections by name, so an agent can route between them without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The clause 'named explicitly rather than left for two separate archive_term_sections calls to be compared by eye' tells the agent this is the preferred path over manual comparison. It gives clear context but states no exclusions, such as what happens if a term is not archived or the course did not exist in one term.

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), so the bar is lower. The description still adds real behavioral value: it discloses that absent fields are surfaced under 'missing_fields' rather than fabricated, and that 'coverage' distinguishes 'course_absent_from_catalog' from 'branch_catalog_missing' – non-obvious semantics an agent could not get from the 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?

Three sentences, each earning its place: the first declares content, the second and third clarify data-integrity semantics. The field enumeration is dense but front-loaded and readable; 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?

An output schema exists, so return values need not be re-explained, yet the description usefully clarifies the two non-obvious output concepts (missing_fields, coverage). The main gap is the unexplained course_code parameter, which is the only real incompleteness.

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 0% for the single parameter, and the description says nothing about course_code – not its format, case sensitivity, or whether it must be an active/archived code. With low coverage the description was expected to compensate and does not.

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 phrase 'Catalog entry for a course from the archive' states the resource and scope, and then enumerates the returned fields, so an agent knows exactly what this retrieves. It does not explicitly differentiate itself from nearby siblings like archive_course_history or archive_search_courses, which keeps it 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?

There is no explicit when-to-use statement, no prerequisites, and no named alternative among the many archive_* siblings. The agent must infer from the field list that this is the full-catalog-lookup tool rather than a search or history tool.

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 and non-destructive, so the safety profile is fully covered. The description adds useful content about what the result contains, but says nothing about the truncation behavior implied by limit_terms or how the archive differs from live data. With annotations doing the heavy lifting, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the resource and output contents, followed by the differentiating use case. No wasted text, though the quoted example could be folded in more tightly.

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 read-only tool with rich annotations and an output schema, the description covers purpose, output shape, and the comparative advantage over OBS. The only real gap is the unexplained default and semantics of limit_terms, which matters for interpreting a truncated history.

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 0%, so the description must carry the parameters; it mentions neither course_code nor limit_terms. The limit_terms parameter in particular is ambiguous (does it cap to the most recent N terms, or truncate arbitrarily?) and the description offers no help, failing to compensate for the schema gap.

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+resource ('Term-by-term offering history for a course from the archive') and enumerates the returned dimensions (terms, sections, instructors, opening season). It explicitly distinguishes the tool from the OBS family ('which OBS cannot'), so an agent can pick it over obs_search_courses without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a concrete motivating question ('is this course ever offered in the spring?') and rules out the OBS tools, which is implicit when-to-use guidance. However, it names no alternatives within the crowded archive_* family (archive_search_courses, archive_term_sections, archive_who_taught), leaving that routing 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), so the bar is lower, yet the description still adds real behavioral context: that prerequisite rules contain AND/OR alternatives and minimum grades this flat list cannot express, and that a 'not_listed_as_prerequisite' coverage value signals an empty result. That is meaningful interpretation guidance beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core lookup semantics are front-loaded in the first sentence, followed by the scope limit and the misreading warning, each in its own sentence with no filler. Nothing could be removed without losing decision-relevant 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?

An output schema exists, so return values need not be re-described, and the description still usefully explains the meaning of the coverage field. The only gap is the undocumented input format for course_code, which for a single-identifier lookup tool is a minor omission.

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 is one required parameter with 0% schema description coverage, so the description carries the full burden of documenting it, and it does not: no format, identifier style, or example for course_code is given. It only refers obliquely to 'the given course', adding nothing beyond what the schema name implies.

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 operation (reverse prerequisite lookup) on a specific resource and explicitly names the direction ('courses that list the given course as a prerequisite'), which separates it from the forward-looking prerequisite siblings. It also scopes the result set ('direct next level only, not the whole chain'), so an agent knows exactly what it will get back.

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 tells the agent when the output is insufficient ('passing the course does not by itself make the listed courses takeable') and routes to a named alternative ('call explain_course_eligibility on a listed course for the real rule'). The scope exclusion against the full chain is stated outright rather than left to inference.

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

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

Annotations already carry the read-only/idempotent/non-destructive safety profile, so the bar is lower. The description adds genuinely useful behavior: most terms have no schedule and the 'coverage' field must be read as 'never captured', not 'no exams' — a nuance not derivable 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?

Three tightly packed sentences, purpose front-loaded, then the coverage caveat, then the alternative route. No filler and nothing that fails to earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape need not be explained, and the key semantic trap about 'coverage' is pre-empted. The only gap is the unmentioned limit parameter, which is minor for a read-only filtered list.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It covers term (implied), branch, and course_code, and adds real meaning with 'exact course code' implying exact-match filtering, but it never mentions the limit parameter or its meaning, leaving one of four params undocumented.

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 ('final exam schedule the archive recorded for a term') with the fields returned (date, day, time, place, exam type), and explicitly distinguishes itself from the live sibling get_public_exam_schedule. An agent can select between the two 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 explicitly ('For the live current schedule use get_public_exam_schedule'), giving a clear when-to-use-this-vs-that rule. It also warns about the common 'exam_schedule_not_recorded' case, telling the agent what to expect and how to interpret 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioural context beyond that: the output differs by input mode (time series vs cross-section capacity snapshot), which is the key trait an agent needs. It omits auth/prerequisite and precedence behaviour when both identifiers are supplied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

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

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

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

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds real behavioral context an agent cannot get elsewhere: same_counts_as terms must not be summed, absent labels mean 'not published' rather than zero, total_mismatch keeps both figures, and coverage can report branch_grades_missing. It does not mention auth or pagination, so not a 5.

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 is front-loaded and nearly every clause carries a real caveat (related_codes, same_counts_as, total_mismatch, coverage). It is delivered as one dense semicolon-chained paragraph rather than clearly separated sentences, which slightly hurts scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be restated, yet the description still supplies the semantic meaning behind its flags, which is the genuinely useful part. The main remaining gap is the optional 'term' parameter's format and default 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 0%, so the description must carry the parameter burden. It clarifies course_code semantics ('only the exact code is used', Turkish/English siblings go under related_codes) and hints that terms look like '2023-2024', but never documents the optional 'term' parameter's format or what omitting it does. Partial compensation warrants the baseline 3.

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+resource+scope: letter grade counts for a course across the terms the archive holds (from 2023-2024 on). The 'archive' framing implicitly separates it from live-data siblings like obs_get_grade_distribution, but no sibling is named explicitly, so it falls just 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?

The description explains how to interpret the returned data but never says when to call this tool versus alternatives such as obs_get_grade_distribution or get_course_grades. There is no when-to-use, when-not-to-use, or prerequisite (e.g., archive availability) 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds two behaviors beyond that: results are ordered newest first, and ambiguous names yield candidate matches rather than a single answer. It still says nothing about pagination behavior relative to the default limit of 40.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action and scope, with the ordering and ambiguity notes packed efficiently. No filler, though the second sentence could carry more parameter detail at the same length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return value shape need not be explained. However, with 0% parameter coverage the description leaves the limit parameter (default 40) and instructor-matching semantics unexplained, which matters for a tool that can return ambiguous candidate sets.

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 0% across two parameters. The description implies instructor is a name (via the ambiguity/candidate-match note) but says nothing about matching syntax or partial names, and the limit parameter is entirely undocumented in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List the courses one instructor has taught across archived terms') plus a scope qualifier (archived terms) that separates it from live-course siblings like list_courses. It does not name the nearest archive siblings (archive_who_taught, archive_course_history) to sharpen the distinction, but the intent is unambiguous.

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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named despite a dense archive_* sibling family. The ambiguity note explains a return behavior, not when to reach for this tool over archive_who_taught or list_courses.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds that results carry section and course counts, which is mild behavioral value, but it says nothing about ordering, pagination, or auth needs beyond what annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the capability stated first and the sibling contrast second. No filler, no repetition of 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?

An output schema exists, so return values need no explanation, and the description covers purpose and routing. The remaining gap is the undocumented term format, which is a minor but real omission for a required parameter.

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 0% for the single 'term' parameter, so the description carries the burden. It clarifies the parameter's scope ('one term's archive dump') but gives no format, valid values, or examples for what a term string looks like.

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 ('List every branch present in one term's archive dump') plus the payload it returns (section and course counts). It also names the sibling it replaces (archive_term_sections), so an agent can distinguish it 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?

Explicitly frames the use case as answering 'does this branch even have a döküm for this term?' and contrasts it with the branch-by-branch probing of archive_term_sections. The alternative and the condition that selects it are both named.

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), so the bar is lower. The description adds genuinely useful behavioral context that annotations cannot express: it returns historical terms OBS no longer publishes plus not-yet-active terms, which matters for downstream calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste, and the core scope statement is front-loaded before the usage hint. Sized exactly to the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. For a zero-parameter listing tool, the description covers scope, inclusion of unpublished terms, and downstream purpose completely.

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 baseline is 4. There is nothing parameter-wise to clarify, and the description correctly adds no spurious parameter discussion.

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 (list every term in the İTÜ ders arşivi) and scopes it precisely (2016-2017 onward, including unpublished and not-yet-active terms). An agent can distinguish it from archive_term_sections or archive_search_courses 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 routes usage: 'Use this to find valid term slugs like 2025-2026-guz for the other archive tools,' establishing it as a prerequisite lookup step. It does not state exclusions or when not to use it, but the intended context is unambiguous.

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, openWorld and non-destructive behavior, so the description rightly focuses on the archive-wide scope ('every term it has ever seen'), which is genuine behavioral context. It stops short of describing result shape or result-count behavior, but the output schema covers 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?

Two tight sentences: the first front-loads what it does and its scope, the second gives the routing guidance. 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?

Purpose, scope and usage are fully covered, safety is handled by annotations, and a return schema exists so return values need no explanation. The only shortfall is silence on the limit/pagination parameter, which matters for a default-20 search 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?

With 0% schema description coverage the description must carry the param burden; it clarifies that the query accepts a code OR a name fragment, which is meaningful beyond the bare 'string' type, but it never mentions the 'limit' parameter or its default of 20.

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 (search) and resource (the archive's full course index) and scopes it precisely to 'across every term it has ever seen — not just the active one,' which cleanly separates it from the sibling active-term searches like list_courses and obs_search_courses.

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 situation to use it ('to find the exact code archive_course_history needs when only a name fragment is known') and names the sibling it feeds, giving the agent a concrete triggering condition and 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 and open-world, so safety is covered. The description adds real behavioral context beyond the structured fields: case-insensitive and Turkish-aware matching, the AND semantics when multiple filters are combined, and which term is used by default. Only the truncation/limit behavior is left implicit.

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: scope first, matching semantics second, routing guidance third, return keys last. No filler sentences, though the third sentence packs several behavioral claims into one long clause.

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 an output schema present, the description need not define return shape, yet it usefully flags match_count, truncated and coverage. Combined with annotations this covers nearly everything an agent needs; only the limit parameter's meaning is unaddressed.

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 0%, so the description carries the burden and does well: it explains that filters combine with AND, that term defaults to the archive's current term, and clarifies course_code/course_name/instructor/day as fragments. The 'limit' parameter is never explained, which is the one gap.

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 (search) and resource (sections) with explicit scope: one whole term across all branches. It enumerates the filter dimensions and explicitly contrasts with archive_term_sections, so an agent can route correctly without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear selection condition ('use this when the branch is unknown or the question spans branches') and names the alternative tool (archive_term_sections) with the case it serves. Both when-to-use and when-to-use-something-else are covered.

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/open-world, so the safety profile is covered. The description adds non-obvious behavioral context: the scraper intentionally pauses outside registration and add/drop weeks, so a stale date is expected rather than an error — a genuinely useful disclosure that prevents misreading the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first lists exactly what is reported, the second pre-empts the only likely misinterpretation (an old date). It is front-loaded and every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description needn't enumerate return fields and doing so is mildly redundant. However, it adds the interpretive caveat about scraping pauses that the schema cannot convey, making the definition complete and safe to act on for a no-param status call.

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 per calibration the baseline is 4. There is nothing for the description to disambiguate, and it correctly spends no words on non-existent 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?

The description states a specific resource (the archive scraper's operational status) and enumerates exactly what it reports: last run, last success, section count, partial-run flag, failed branches and data age. An agent can distinguish this status/diagnostic tool from the data-querying archive_* siblings, though no sibling is named 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?

The phrase 'Informational only' signal intent and the staleness caveat steers interpretation of the result, but the description never states when an agent should call this versus other archive tools or what to do with the output. Usage is implied 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 readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds a genuinely useful behavioral fact beyond that: the archive contains not-yet-published terms, which changes how an agent should interpret results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, filter behavior first, the key archive caveat second. 'Critically' is slightly editorial but the content earns its space; nothing is redundant.

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 an output schema present, return values need not be explained. The description covers purpose, filters and the key unpublished-terms insight, leaving only limit/pagination behavior unaddressed, which is a minor gap.

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 0%, so the description carries the burden and does mention term, branch, course code and instructor, giving each a filtering role. It omits the limit parameter entirely and provides no format guidance (e.g. term string shape), so it only partially compensates.

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 (archived term sections), plus the filter axes. However, it does not differentiate itself from the very close sibling archive_search_sections, so an agent must still infer which of the two archive-sections tools to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when this tool is valuable: the archive holds terms OBS has not published yet, so upcoming offerings can be checked. It stops short of naming an alternative or an explicit exclusion, so it is context rather than 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description adds that results are ranked by term count and include most-recent-term and average fill rate, which is useful but is really output content rather than behavior 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 dense sentence that front-loads the core action and packs the ranking, recency, and fill-rate details with 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?

An output schema exists, so the description need not explain return values, and the safety profile is covered by annotations. However, with two parameters at 0% coverage and no usage routing against a large sibling archive_* family, the definition is only adequate for an agent 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?

Schema description coverage is 0%, so both parameters depend on the description. course_code is inferable from 'a course', but limit_terms is never mentioned or explained — it is unclear whether it caps the number of terms, instructors, or rows. The description does not compensate for the documentation gap.

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 ('list'), a precise resource ('every instructor who has taught a course'), and a scoping constraint ('across archived terms'), plus the ranking dimension. An agent can distinguish it from siblings like archive_instructor_courses or archive_course_history, though the description never explicitly contrasts 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?

Usage is only implied by the phrase 'across archived terms' and the required course_code. There is no statement of when to prefer this over archive_instructor_courses, archive_term_sections, or archive_compare_terms, and no exclusions or prerequisites are given.

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 genuinely new context by defining the two-part check (configuration presence + session viability), which tells the agent what success and failure mean. It stops short of saying whether the session probe has side effects or what remediation follows a failure.

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 front-loaded sentence with no filler; the check conditions are ordered from cheapest (is config present) to more involved (can a session be created).

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 an output schema present, the description need not enumerate return values, and with no parameters there is no input surface to document. It is adequate for this complexity level, with the only soft spot being the unstated relationship to obs_auth_status and refresh_session in a very crowded sibling set.

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 per the rubric the baseline is 4. There is nothing for the description to disambiguate, and the schema coverage is 100%.

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 ('Check') and two concrete objects ('Ninova credentials are configured', 'a fresh session can be created'), which is more precise than a bare 'get status'. Naming 'Ninova' implicitly separates it from the many credential/session siblings (obs_auth_status, mail_status), though it never states that contrast 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 only implied: an agent can infer this is a diagnostic probe to run before/after other authenticated calls, but there is no explicit when-to-use, no prerequisites, and no mention of the related refresh_session or obs_auth_status alternatives. It routes nothing.

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, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description clarifies it is a read (useful against the misleading 'build' name) and notes the default-selection behavior, but adds little further context about scope, permissions, or what happens when plan_id is supplied versus omitted.

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 clean sentence with the key default behavior front-loaded and no filler. It is efficient, though the brevity is arguably under-specification for a five-parameter tool rather than true conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need no explanation, but with 5 parameters at 0% schema coverage and a name that contradicts the described read-only behavior, the definition leaves the agent without enough to call this correctly — especially the required faculty_id/program_code pairing and the role of plan_id vs latest.

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 0% across five parameters, yet the description only touches the 'latest' flag (and duplicates its schema default). faculty_id, program_code, plan_id, and plan_type (a Turkish-language enum-like value "lisans") are left entirely unexplained, so the description fails to compensate for the coverage gap.

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 verb ("Read") and a resource ("official semester-by-semester OBS curriculum"), which is far clearer than the tool name 'build_degree_plan' implies — 'build' suggests construction, not retrieval. However, it does not differentiate this tool from close siblings such as list_degree_programs or plan_remaining_courses, leaving the agent to guess which one returns the curriculum.

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 only guidance is that the latest plan is selected by default, which is really a parameter default rather than a when-to-use rule. There is no statement of when to use this versus list_degree_programs/plan_remaining_courses, and no prerequisites or exclusions.

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 the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint). The description's only added context is the no-transcript framing, which is mildly useful but does not disclose any behavior the annotations don't already imply for a pure calculation.

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, front-loaded sentence with no filler. The action and scope are stated immediately, and nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 4-input calculator with a complete annotation set and an output schema (so return values need no explanation), the description covers what the tool computes. It is only slightly thin on distinguishing itself from the sibling GPA tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should compensate, and it does not explain any of the four parameters. The parameter names (current_gpa, current_credits, target_gpa, future_credits) are largely self-describing, keeping this at the minimum-viable baseline rather than lower.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb (Estimate) and resource (future average required to reach a target cumulative GPA) make the tool's function unambiguous. It does not, however, distinguish itself from the sibling obs_calculate_gpa or estimate_relative_grade, which the agent may confuse it 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 phrase 'without reading a transcript' implies when to prefer this tool (planning/forward-looking, no transcript access needed) versus transcript-dependent siblings, but the guidance is only implied. No explicit when/when-not or named alternative is given.

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 non-destructive behavior, so the safety profile is covered. The description usefully adds the data source ('public course schedule' for day/time/room), implying results may not reflect a student's personal registration record, but it says nothing about auth requirements, invalid-CRN handling, or result granularity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the core action front-loaded and the data-source detail second. No filler, though the second sentence could carry a bit more of the missing parameter context at negligible cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. However, with three undocumented input parameters and no guidance on how conflicting CRNs outside the given department/program are treated, the definition is only minimally complete for a 4-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 4 parameters, so the description carries the full burden, yet it only clarifies that crns are CRN identifiers. The roles of program_type, department_code and department_codes (with defaults LS/BLG) are left completely unexplained, leaving most parameters ambiguous.

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 verb and resource ('Check for schedule time conflicts between courses') and pins the identifier type ('by CRN'), so it is distinguishable from neighbors like get_public_course_schedule or obs_validate_registration_plan. It never explicitly names a sibling it is not, which keeps it 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?

Usage is only implied: an agent can infer this is the pre-registration conflict check, and the description notes the data comes from the public schedule. There is no statement of when to prefer this over obs_validate_registration_plan or find_open_course_sections, and no exclusions or prerequisites.

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?

Goes well beyond annotations with concrete semantics: status meanings ('unknown' is never a free seat, 'not_listed' ≠ full, 'stale_term' is not compared), first-check baseline behavior, no background execution/notifications, and short-lived schedule caching with a freshness flag and retry delay. This is exactly the kind of state/caching disclosure the structured fields 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 the core action, then status semantics, then one-shot/caching constraints. It is dense but every sentence carries operational information; slightly long, yet no filler or repetition to cut.

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 check with an output schema, the description supplies everything an agent needs: what to expect, how to read the statuses, and how to behave under caching. Return-value structure is covered by the output schema, so no gap remains.

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 per the rules the baseline is 4; the description correctly implies the operation is parameterless and identifies the watched set as the implicit input. Nothing further is needed on parameter semantics.

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+scope: 'Read the public OBS schedule now for the watched sections (one request per branch, no login).' It immediately names what is reported per section (capacity, enrolled, seats free, changes), which distinguishes it from sibling watch/unwatch/list-watched tools. No ambiguity about what the call does.

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 context: it is a one-shot check, cannot run in the background, and 'a periodic check must be driven by the user or by a scheduled task on the client.' It also tells the caller not to loop when 'freshness.all_from_cache' is true and to wait 'retry_after_seconds' instead. It stops short of explicitly naming a sibling alternative (e.g., watch_course_sections to add sections first), so not 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, giving the safety profile for free. The description adds that the crawl inventories pages plus downloadable resources, but says nothing about rate limits, depth/page caps, or what happens at traversal boundaries, so it only modestly exceeds 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 front-loaded sentence with no padding; the core scope is stated immediately. It is efficient, though it borders on under-specification rather than reaching maximal usefulness.

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?

The presence of an output schema means return values need not be described, and annotations cover the safety profile. However, for a crawl tool with depth, page-count, and download-toggle parameters, the description leaves parameter behavior and usage context unexplained, so it is only adequate.

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 0% across four parameters (max_depth, max_pages, course_url, include_downloads), so the schema documents none of them and the description must compensate. It only loosely gestures at 'downloadable resources' (related to include_downloads) and never explains depth, page limits, or the required URL's expected form.

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 ('Inventory') and resource ('pages and downloadable resources') scoped to a 'Ninova course tree', which is clearer than the bare tool name. It does not explicitly name the sibling it differs from (read_page, snapshot_page, download_resource), so sibling differentiation is left implicit.

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?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives like read_page, snapshot_page, or download_resource. The agent must infer that this is a bulk-discovery tool versus the single-item siblings.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the comparison-against-stored-state idea, which is already implied by the name and parameters; it says nothing about behavior when no snapshot exists or how diffs are presented.

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 front-loaded sentence with no filler; the verb and both operands appear immediately. Nothing wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the tool is read-only and single-purpose. However, the ambiguity over how the target snapshot is identified (label vs snapshot_path, and the failure mode when neither is valid) leaves a real operational hole for an agent.

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 0% for all three parameters, and the description does not compensate. It does not explain what url points at, what label means as a snapshot identifier, what snapshot_path is, or how label and snapshot_path interact (e.g., mutually exclusive selectors).

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 (compare) and both resources: the current page state and a previously stored snapshot. It is clear what the tool does, though it does not name its closest sibling snapshot_page, leaving the create-vs-compare relationship to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to use this versus read_page or snapshot_page, and no prerequisites. The phrase 'previously stored snapshot' hints that a snapshot must exist first, but the description never says how it is created or what happens if it is absent.

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=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered structurally. The description contributes the auth requirement ('authenticated resource') and the fact that output lands on disk, but says nothing about overwrite behavior for existing files, default output location, or failure modes.

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 front-loaded sentence with no filler or redundancy. It is tight, though its brevity contributes to the underspecification scored in other dimensions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, but for a three-parameter disk-write tool with 0% schema description coverage the description omits critical operational detail: default download directory, filename derivation, overwrite semantics, and auth prerequisites beyond the adjective 'authenticated'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description names none of the three parameters. 'Authenticated resource' faintly hints that url must be a session-accessible resource, but filename and output_dir (including their null defaults and where files land when omitted) are left entirely unexplained in both schema and description.

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 ('Download') and resource ('Ninova file or other authenticated resource') with the destination ('to disk'), which separates it from read_resource_text, which reads content rather than saving it. It does not explicitly name or contrast any sibling, so it stops 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?

Usage is only implied: 'to disk' signals the save-to-local-filesystem scenario, and 'authenticated resource' scopes it to resources the session can access. There is no explicit when-to-use, when-not-to-use, or named alternative such as read_resource_text or get_course_class_files.

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 read-only/idempotent safety, and the description adds crucial context beyond that: it explains each method's data dependency (Table 1 example table vs. fixed Table 2 formula), the caveat that instructors may override cutoffs, that output is an estimate, and the VF-exclusion rule for the average. This is genuine behavioral context, not restatement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences that are front-loaded with the core purpose. The parenthetical about Method 1's example-table caveat is essential, not filler, though the sentence is long and the second sentence packs several clauses that could be split.

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 2-param estimation tool with a rich caveat set, the description covers the essential guidance (what to pass, VF exclusion, estimate-only nature, method differentiation). An output schema exists so return formatting needn't be explained. The only gap is my_score's expected range/format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and param names are opaque, so the description must carry the load. It does well for class_scores (must be every counting student's raw 0-100 score, VF excluded) but says nothing about my_score's constraints or format, leaving that parameter undocumented.

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+resource+method: 'estimate a likely letter grade from raw class scores under İTÜ's relative-grading rules' and names both official methods. This is well-differentiated from siblings like obs_get_grade_distribution or obs_calculate_gpa, which are observational/calculation tools rather than an estimation tool.

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?

Clearly scopes usage: 'for planning purposes only, not the official grade' and specifies exactly what class_scores must contain (every counting student, VF excluded). It does not name an alternative tool for official grades, but the audience and purpose are unambiguous.

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

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

Annotations cover the safety profile (read-only, idempotent, non-destructive, open-world), and the description adds substantial behavior beyond them: it warns never to read an empty result as 'no prerequisites', explains OBS is authoritative when cross_check disagrees and that disagreements are reported not resolved, and flags term-only offerings. This is exactly the edge-case disclosure 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 core purpose in the first clause, then adds behavioral caveats in decreasing priority. Dense but every sentence carries a distinct warning; only the quoted-token style is slightly heavy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, and the behavioral framing is strong. The gap is that a 6-parameter tool with 0% schema coverage leaves the inputs undocumented, and references to 'cross_check'/'archive_seasonality' are ambiguous between inputs and outputs.

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 0% and the description explains none of the six inputs (course_code, class_year, program_type, use_obs_history, completed_courses, completed_credits). It instead discusses terms ('prerequisite_status', 'cross_check', 'archive_seasonality') that don't appear as parameters, which risks confusing the agent about what can be passed versus what is returned.

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 (explain) and resource (course eligibility/prerequisites) plus the authoritative source (official OBS branch prerequisite table), and distinguishes the tool from the community dataset it cross-checks against. An agent can tell this apart from obs_get_course_prerequisites and get_public_course_prerequisites 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?

Offers some conditional guidance ('check archive_seasonality even when eligibility alone looks fine') and explains when a status is 'unknown' vs 'no_prerequisites'. However, it never explicitly routes the agent between this tool and the many sibling prerequisite tools (obs_get_course_prerequisites, get_public_course_prerequisites), so the when-to-use decision is only 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 read-only/idempotent/non-destructive/openWorld, and the description adds substantial extra behavior: Europe/Istanbul timezone, weekly recurrence spanning first-to-last class day, holidays not excluded, the status='term_dates_required' failure mode, and that it returns text without writing a file.

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, leading with what the tool builds before edge-case handling. It runs long across several sentences, but nearly every clause carries decision-relevant information, so little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description needn't enumerate returns, yet it still explains the 'ics', 'skipped', and 'missing_crns' outputs and the failure mode. 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?

With 0% schema description coverage the description must carry parameter meaning, and it does: crns drive weekly meetings, department_codes define the scanned departments, and term_start/term_end are the first/last day of classes. Only program_type is left unexplained, a minor gap.

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 artifact ('Build an iCalendar (.ics) document') from a specific source (weekly meetings of the given CRNs, public OBS course schedule). This clearly distinguishes it from the sibling export_exam_schedule_ics and from read-only schedule viewers.

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 actionable context: no login required, and when term_start/term_end are omitted the academic calendar only covers the displayed month, so the agent should ask the user for dates rather than guess. It does not explicitly compare itself to the exam-schedule export sibling, but the operating guidance is 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?

Goes well beyond annotations: documents the exact output field ('ics'), edge-case behaviors ('skipped', 'not_found', 'exam_schedule_not_published', 'end_time_unknown'), time zone, and crucially that it does not write a file. Annotations confirm read-only, but the description adds rich behavioral detail about error states and output semantics.

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 main action and output, then lists edge cases efficiently. Two long sentences but no filler; every clause carries information about behavior or output.

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?

Covers output location ('ics'), non-file-writing behavior, time zone, and all major failure modes. For a read-only export tool with an output schema, this is complete enough that an agent could invoke it correctly without further guidance.

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 0%, so the description must compensate. It explains that course_codes filters the schedule, which is useful, but does not clarify format expectations (e.g., exact code format like 'CS101'). Baseline 3 is appropriate given some meaning is added but the parameter remains under-specified.

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 (Build) and a precise resource (iCalendar .ics from the public OBS final exam schedule), and scopes it as filtered by course codes. Clearly distinguishable from siblings like export_course_schedule_ics and get_public_exam_schedule.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (no login required, public schedule) but does not explicitly state when to use this instead of get_public_exam_schedule or export_course_schedule_ics. The 'no login' hint gives context but no alternative 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 cover the safety profile: readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint. The description adds that results are an 'estimate' based on public department schedules, which usefully signals approximate rather than authoritative availability. It does not, however, disclose accuracy limits, auth needs, or whether all rooms are covered.

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 a single front-loaded sentence with no filler. It is appropriately concise, though its brevity contributes to the missing parameter and usage detail noted in other dimensions.

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 tool with five parameters, including two optional fields with no schema descriptions, the description is too sparse. The presence of an output schema means return values need not be explained, but the description still fails to explain how to use department_codes, building, or program_type 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 0%, so the description must compensate for five undocumented parameters. It maps loosely to day, time, and department_codes via 'weekday/time' and 'selected public department schedules,' but says nothing about the optional building parameter or the program_type parameter with default 'LS'.

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 provides a clear verb and resource: estimating empty rooms/classrooms at a specific weekday and time. It also implies the data scope is public department schedules, which helps distinguish it from personal schedule tools. However, it does not explicitly differentiate itself from related siblings such as get_public_course_schedule or search_campus_locations.

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 does not state when to use this tool versus alternatives, nor does it provide prerequisites, exclusions, or expected input context. The only usage cue is that results come from 'selected public department schedules,' which is a data-source note rather than invocation 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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety and repeatability are covered. The description adds one useful behavioral fact — it searches public department schedule data rather than the user's own enrollment — but says nothing about result volume, pagination, or freshness of seat counts, which is the key risk for an availability query.

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?

One sentence, front-loaded with the action and filter, with no filler or redundancy. Nothing in it is wasted, though brevity here comes at the cost of the missing details noted elsewhere.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be re-explained, but with 0% schema description coverage the description leaves core search semantics (free-text query, program type filtering, seat threshold behavior) undefined. For a 4-parameter search tool with an open-world annotation, this is too thin for reliable invocation.

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 0% across 4 parameters, so the description carries the burden and mostly fails. "Department schedules" loosely maps to department_codes and "available seats" to min_available_seats, but query and program_type (default "LS") are entirely unexplained, including whether query is a free-text course search.

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 ("Find") and resource ("sections with available seats") with a scoping qualifier ("public OBS department schedules"), which separates it from personal-schedule siblings like get_course_sections or obs_get_schedule. However, it never names or contrasts with the close alternatives (get_course_sections, obs_search_courses, archive_search_sections), leaving differentiation to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_course_sections (all sections) versus this tool (open seats only). The "available seats" framing hints at intent but the agent must guess which sibling to pick.

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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the '(public, no login)' auth context, which is genuinely beyond the annotations. It does not describe pagination, filtering behavior, or result shape.

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 front-loaded sentence with the resource named first and the content enumeration following. No waste, though it is terse enough to omit useful detail rather than being optimally informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return-value format need not be explained, and the description covers the topical content well. The main gap is the four undocumented optional parameters, which are neither described in the schema nor the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% across four parameters (query, date_to, date_from, category) and the description mentions none of them. It does not explain what 'query' searches, what format dates take, or what 'category' accepts, leaving the agent to infer everything from parameter names.

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 ('Read') and resource ('İTÜ academic calendar') and enumerates the content covered (semester dates, exams, holidays, registration periods). It is clear what the tool returns, though it does not explicitly contrast itself with siblings like get_upcoming_deadlines or get_public_exam_schedule.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no when-to-use guidance or alternatives; it never explains how this differs from get_upcoming_deadlines, get_public_exam_schedule, or get_personal_exam_calendar. The '(public, no login)' note is a mild access hint but not a usage rule.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the result includes which slots are filled and allowed extensions, which is useful behavioral context beyond the annotations, but it doesn't mention authentication requirements, rate limits, or error behavior.

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 a single, front-loaded sentence that efficiently states what the tool returns. It's appropriately sized and wastes no words, though it could be slightly more structured with usage 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?

An output schema exists, so return value details need not be explained. However, for a tool with three undocumented parameters and no usage guidance, the description leaves significant gaps for an agent to invoke it correctly, especially regarding when to use it versus submit_assignment.

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 0% and all three parameters (course, assignment, upload_url) are undocumented. The description doesn't explain what these parameters mean, whether any are required, or how to supply them. With zero schema coverage, the description should compensate but does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: listing file slots on an assignment's upload page, and it names the relevant page identifiers. It distinguishes itself from the sibling submit_assignment (which writes) by being a read/list operation, though it doesn't explicitly call out that relationship.

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 gives no explicit when-to-use or when-not-to-use guidance. It doesn't mention the sibling tool submit_assignment, nor does it explain whether this should be called before uploading or as part of a workflow.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds valuable context beyond that by flagging the login requirement, but says nothing about rate limits, behavior on invalid/missing dates, or how a null date is interpreted.

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 tightly-packed sentence with the resource front-loaded and the auth caveat placed inline. Every clause earns its place and nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description is right not to explain return values despite mentioning calories and allergens. What is missing is parameter-level completeness: with 0% schema coverage and no enums, the date and meal value formats should have been spelled out somewhere, and they are not.

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 0% and there are no enums, so the description carries the full burden. 'Dated' weakly implies the date parameter accepts a date and 'lunch/dinner or vegan' hints at meal/vegan values, but the date format (ISO? relative?) and valid meal strings are never specified, leaving the agent to guess on a tool where the schema offers nothing.

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 (Read) plus resource (dated lunch/dinner or vegan menu) and names the source (İTÜ Portal) and content (calories, allergens). No sibling tool covers cafeteria menus, so no differentiation is needed. It stops short of 5 only because the 'lunch/dinner or vegan' phrasing is slightly ambiguous about whether vegan is a meal category or a flag.

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 parenthetical '(requires login)' is a genuine precondition that tells the agent when this call will fail and may need an auth step first. However, it gives no guidance on defaults (all three params are optional with null defaults), no example date format, and no indication of what happens when date or meal is omitted.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no pagination behavior, no indication of what 'compact' or 'include_full_text' change about the result, and no note on how many announcements are returned by default.

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 front-loaded sentence with zero filler is structurally clean, but at this length it is terse rather than concise — it omits information the agent needs, so brevity here costs more than it saves.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. But with four parameters at 0% schema coverage and a dense sibling set of announcement-related tools, the definition is too thin to let an agent invoke it confidently.

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 0% across four parameters, so the description is the only chance to explain them. It alludes only to 'course' and says nothing about limit (default 50), compact, or include_full_text, which are the genuinely opaque flags; the compensation required for low coverage is absent.

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 verb+resource ('Return announcements') and scopes it to 'a specific Ninova course', which is concrete and readable. However, it never distinguishes this tool from the sibling get_dashboard_announcements or get_itu_announcements, so scope boundaries must be inferred from the name.

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?

There is no when-to-use guidance, no prerequisite or auth context, and no routing to alternatives such as get_dashboard_announcements for cross-course announcements. The agent is left to guess which announcement tool applies.

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 safe read profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds meaningful behavior beyond that: by default the call fans out to fetch each assignment's detail/upload page, and this can be disabled for speed. That cost/behavior disclosure is exactly the kind of context annotations don't 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?

Two sentences, zero waste. The default behavior is stated first and the opt-out is front-loaded immediately after, so the agent can act without scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the read-only annotations cover safety. The description completes the picture on default-vs-optimized behavior, but leaves the limit/compact parameters and course identifier format unaddressed.

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 0%, so the description must compensate, and it only explains include_details (the most consequential flag) while leaving limit and especially the ambiguous compact parameter undefined. The 'course' argument is self-evident, but the overall coverage gap keeps this at a partial-compensation level.

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: return a course's assignment list. This is clearly scoped to a single course, distinguishing it from siblings like get_dashboard_assignments. It does not explicitly name any sibling, so it stops 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 a real tradeoff for one parameter (default fetches details; include_details=false is a faster list-only read), which is genuine usage guidance. However, there is no when-to-use-this-vs-alternatives direction, e.g. versus get_dashboard_assignments or get_assignment_upload_slots, so guidance is implied rather than explicit.

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 genuinely useful context beyond that: the data is instructor-recorded LMS data, not the official OBS record, which affects trust and interpretation. It does not discuss auth requirements, but that gap is minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two front-loaded sentences with zero filler: the what/where comes first, the alternative routing second. Every clause earns its place.

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 simple read-only lookup with an output schema present, return values need not be explained and annotations cover safety. The description supplies the one thing that matters – the distinction from the official OBS attendance tool – so 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 description coverage is 0% for the single 'course' parameter, so the description carries the burden. Its phrase 'for a course' implies a course identifier but gives no format (course code, ID, section), so it only partially compensates. A 3 reflects the modest value added over the bare 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 (Read) and resource (the Ninova 'Yoklama' page for a course) and immediately scopes it against the OBS record. An agent can distinguish it from obs_get_attendance 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?

Explicitly names the alternative (obs_get_attendance) and the condition that selects it ('official attendance with an absence-risk summary'). The when-to-use routing is unambiguous.

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 openWorld, so the safety profile is covered. The description adds only the section location and says nothing about behavior tied to the recursive/max_depth options or any auth/session requirements, so it adds little beyond 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?

A single efficient sentence with no wasted words and the scope front-loaded. It is appropriately sized, though thin given the parameter surface it needs to cover.

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 4-parameter tool with 0% schema description coverage, the description is too sparse. The output schema and annotations cover return shape and safety, but the behavioral meaning of the recursion/depth parameters is missing entirely.

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 0%, so the description must compensate, yet it only implies the 'course' parameter and says nothing about compact, max_depth, or recursive. Three optional parameters that materially change the listing behavior are left completely unexplained.

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 (files and folders) plus the exact Ninova section ('Sınıf Dosyaları') scoping it to a course. However, it does nothing to distinguish itself from the near-identical sibling get_course_lesson_files, leaving the agent to guess which section each targets.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives. With a sibling like get_course_lesson_files in the toolset, the description should route the agent but offers no condition for choosing this tool.

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, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context by identifying the data source (LMS-entered vs official record), though it says nothing about auth requirements, caching, or freshness of the LMS 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?

Two clauses, zero waste, front-loaded with the purpose and immediately followed by the disambiguation routing. Every sentence earns its place.

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 an output schema present, return values needn't be explained. Purpose, data-source distinction, and the alternative are all present; the only gap is the undocumented 'course' identifier format, which is a minor omission for a single-param 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 single 'course' parameter has 0% schema description coverage, and the description only says 'for a course' without specifying the expected format (course code, section ID, name). For a low-coverage schema the description should compensate by clarifying the identifier format, which it does not.

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 (Read) and resource (the Ninova 'Notlar' page for a course) and clarifies the exact data semantics — instructor-entered LMS grades, not the official transcript. It explicitly names the sibling it is distinct from (obs_get_course_grades), so an agent can separate the two 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?

Provides both when-to-use (LMS/instructor grades) and when-not-to-use with a named alternative (obs_get_course_grades for official letter/midterm grades). The routing condition is explicit and unambiguous.

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, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds no behavioral context beyond that — no mention of auth requirements, scoping (own courses vs. any course), or freshness of the scraped page.

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, front-loaded sentence with no filler. It is efficient, though its brevity comes at the cost of the missing information noted elsewhere.

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?

The tool is structurally simple (one param) with a full output schema and rich annotations, so return values and safety need not be described. However, given ~90 sibling tools including several near-duplicate course getters, the description is not complete enough for an agent to choose this one confidently.

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 0% for the single 'course' parameter, and the description does not compensate at all — it never says whether 'course' expects a course code, a numeric ID, or a name, nor gives an example. This is a real gap for the one input the caller must supply.

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 verb+resource ('Return structured information from a course's page') is identifiable, but 'structured information' is vague and the tool is not distinguished from near-identical siblings like get_course_overview, get_course_sections, or get_course_grades. Referencing the 'Sınıf Bilgileri' page adds a little specificity about the data source but not about the content returned.

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?

There is no statement of when to use this tool versus the many sibling course tools, nor any prerequisites (e.g., must the student be enrolled, must a session be authenticated). The agent is left to infer usage entirely.

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 only the scope ('Ders Dosyaları' section) and says nothing about recursion behavior, depth limits, or result size, which is the one piece of behavior an agent would actually need here.

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 front-loaded sentence with the scope qualifier placed before the noun; no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and annotations cover safety. Still, for a 4-parameter, open-world listing tool the description omits traversal semantics and sibling disambiguation, leaving it only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description mentions none of the four parameters — notably 'recursive' (default true) and 'max_depth' (default 3), which materially change what is returned. The description must compensate for the empty schema and does not.

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 ('List') and resource ('files and folders') and scopes it to a named Ninova section, so an agent knows exactly what surface it reads. It does not, however, distinguish itself from the very similar sibling 'get_course_class_files', leaving ambiguity between the two.

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?

There is no statement of when to use this tool versus alternatives, no prerequisites (e.g. enrollment/auth), and no exclusion note. With a near-identical sibling ('get_course_class_files') present, the absence of routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description's 'Read' merely restates readOnlyHint and adds no new behavioral context such as pagination, authentication requirements, or what a scrape of the Ninova page entails.

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 with no filler, and the resource is front-loaded. It is concise to the point of being under-specified rather than wasteful, so it lands at minimum-viable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, and annotations cover safety, but for a three-parameter course tool in a very crowded sibling set the description supplies no usage routing and no parameter meaning at all.

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 0% and there are three parameters, including the non-obvious include_thread_details flag and a limit with default 50. The description mentions none of them or their formats, so it fails to compensate for the coverage gap.

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 (read) and a specific resource (the Ninova 'Mesaj Panosu' page) scoped to a course, which is more concrete than a tautology. It does not, however, differentiate itself from near siblings like get_course_announcements or read_page, leaving the agent to infer the distinction.

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?

There is no when-to-use guidance, no exclusions, and no named alternative. With siblings such as get_course_announcements, read_page, and get_course_overview competing for the same course-content intent, the description gives the agent nothing to arbitrate with.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the aggregation scope but says nothing about what 'refresh' triggers (network re-fetch / cache invalidation) or the performance cost of the combined pull, which are the behaviors an agent would actually need.

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 dense sentence that front-loads the verb and enumerates scope with zero filler. Efficient, though the long comma list trades readability for compactness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is rightly omitted, and annotations cover safety. However, with 5 parameters at 0% schema coverage and no description of them, plus an unexplained 'refresh' mutation-ish behavior, the definition leaves real gaps for correct invocation.

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 0% across 5 parameters, so the description carries the full burden and fails it: compact, refresh, file_max_depth, and include_assignment_details are never mentioned. Only faint hints exist via the nouns 'files' and 'assignments' in the return list, which does not convey what those flags change.

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?

Clear verb ('Return') and resource ('a course's sections, announcements, assignments...'), and it explicitly identifies itself as a 'combined view', which distinguishes it from the ~10 granular get_course_* siblings. It stops short of naming those siblings or stating the aggregate-vs-granular tradeoff, so an agent must infer the 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?

The word 'combined' implies this is the bulk-fetch option versus get_course_sections/get_course_announcements/etc., but there is no explicit when-to-use statement, no condition for choosing it over the granular siblings, and no note on cost or latency of fetching everything.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond that — no note on authentication requirements, what the page contains, or whether the course must be one the user is enrolled in. With annotations carrying the safety load, the description contributes almost nothing extra.

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 front-loaded sentence with no filler, which is appropriately tight given the simplicity of the tool. Its brevity is the issue only insofar as it is under-specified, not because it wastes 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?

An output schema exists, so return values need not be described, but the definition still leaves the single required parameter format undocumented and does not distinguish this page reader from its many siblings. For a tool whose one input is completely unspecified, this is incomplete.

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 is one required parameter ('course') and schema description coverage is 0%, so the description carries the full burden — yet it only says 'for a course', restating the parameter name. It gives no hint whether the value is a course code, CRN, numeric ID, or name, leaving the agent to guess the format.

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 verb ('Read') and a specific resource (the Ninova 'Uzaktan Eğitim' page) scoped to a course, which is clearer than a generic 'get course X'. However, it offers no differentiation from the many sibling get_course_* page readers (get_course_info, get_course_announcements, etc.) or from crawl_course/read_page, so an agent must infer which page this targets.

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?

There is no when-to-use, when-not-to-use, or alternative-selection guidance. The agent is not told why it would pick this remote-learning page over read_page, crawl_course, or another get_course_* reader, nor any precondition (e.g., enrollment in the course).

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/non-destructive, so the safety profile is covered. The description adds only the mild scoping detail that results come from the Ninova course home page; it says nothing about freshness, caching, or coverage limits. An output schema exists, so return details are not required here.

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 with no wasted words and a front-loaded verb. It is efficient, though its brevity is partly a symptom of under-specification rather than disciplined concision.

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 an output schema present, return values need not be explained, but the description still leaves the core noun ('routes') undefined and the required course parameter format unaddressed. For a one-required-param tool with zero schema coverage, more context is needed.

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 0% and the single required 'course' parameter is undocumented in both schema and description. The description gives no hint about the accepted identifier format (course code, numeric ID, slug), so the agent cannot reliably populate 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?

The verb 'List' and the resource (course sections, per the name) are present, but the description calls them 'direct course routes exposed on the Ninova course home page,' which is opaque terminology that doesn't clearly match the tool name or distinguish it from siblings like find_open_course_sections or archive_term_sections. An agent can guess the general domain but not precisely what a 'route' is here.

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?

No when-to-use, when-not-to-use, or alternative guidance is provided, despite a dense family of related siblings (find_open_course_sections, watch_course_sections, archive_search_sections). The agent is left to infer the use case entirely on its own.

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 that this is an aggregating read spanning four distinct content types, which is modest added context, but it says nothing about authentication requirements or rate/refresh behavior for what is clearly a session-bound scrape.

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?

One sentence, front-loaded with the verb and resource, with the content types listed after. No filler, though the sentence is a bare enumeration and could have carried one clause of guidance at no length cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return formatting need not be explained, and the read/aggregate scope is stated. What remains missing is the meaning of 'compact' and any hint of prerequisites (e.g. authenticated Ninova session) for a tool with openWorldHint.

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 single parameter 'compact' has 0% schema description coverage and is never mentioned in the description, so an agent has no idea what it does or when to enable it. With one undocumented parameter, the description fails to compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Read') plus resource ('the Ninova dashboard') and an explicit enumeration of what gets summarized (courses, announcements, assignments, messages). It is distinguishable from narrow siblings such as get_dashboard_announcements and get_dashboard_assignments, though those siblings are never named.

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?

No when-to-use, when-not-to-use, or alternative guidance is given. The presence of get_dashboard_announcements and get_dashboard_assignments in the sibling list makes the 'overview vs. drill-down' choice an obvious question the description leaves unanswered.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The phrase 'aggregated announcements page' adds a small hint that results are assembled from multiple sources, but nothing about freshness, ordering, or pagination is 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?

A single efficient sentence with the resource and scope front-loaded and no filler. It is well-formed, though very short given how much is left unspecified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value shape need not be described. However, against a large sibling set of announcement-related tools, the description omits both usage routing and any explanation of its two undocumented parameters, leaving the definition only marginally sufficient.

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 0% and neither parameter (limit, include_full_text) is mentioned in the description. Defaults are visible in the schema, but the description does nothing to explain what 'full text' means or how limit affects the aggregated result, so it fails to compensate for the coverage gap.

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 (Return) and a specific resource (announcements listed under the Ninova dashboard's aggregated announcements page). This implicitly separates it from course-level siblings like get_course_announcements and get_itu_announcements, though it never names them 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?

There is no when-to-use guidance at all. With near-identical siblings (get_course_announcements, get_itu_announcements, get_updates, get_dashboard), the agent gets no rule for choosing this tool over those.

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 a genuine behavioral tradeoff not present in the annotations: that include_details=false yields a faster, list-only read. It does not disclose pagination behavior, the meaning of the default 20-item limit, or whether results span all enrolled courses.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core purpose front-loaded and the performance tip following. Nothing in the text is redundant with the title or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the safety profile is fully carried by annotations. The remaining gap is the undocumented limit parameter and the imprecise word "aggregated" (across courses? across terms?), which an agent may need to resolve to call this confidently.

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 0%, so the description carries the burden for both parameters. It explains the include_details tradeoff well but says nothing about limit, leaving half the parameters undocumented in both the schema and the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Return the assignments listed under the Ninova dashboard's aggregated assignments page"), making it clear this is a dashboard-scoped assignment list. It does not, however, distinguish itself from closely named siblings such as get_course_assignments, get_upcoming_deadlines, or get_dashboard, leaving the agent to infer the boundary.

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 only guidance is a parameter-tuning hint ("Set include_details=false for a faster list-only read"), which is useful but is not a when-to-use rule. There is no statement of when this tool should be chosen over get_course_assignments or get_upcoming_deadlines, and no exclusions.

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/open-world, so the bar is lower, and the description still adds real behavior: login requirement, no attachment download, reply detection by comparing history authors to the original requester, null for missing fields, and source-local dates with no assumed timezone. It stops short of error behavior for an invalid or inaccessible ticket ID.

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: the core purpose leads, followed by scope, semantics, and prerequisites in short declarative clauses. Every sentence earns its place (null handling, timezone, auth), though the field enumeration partially duplicates what the output schema will return.

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 a rich annotation set and an output schema present, the description does not need to explain return values, and it covers auth, scope, null and timezone semantics well. The remaining gap is include_sensitive, whose effect is undocumented anywhere, leaving the default behavior unstated.

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 0%, so the description must carry both parameters and it only half does. 'numeric ID' describes ticket_id but actually conflicts with the schema type (string), and include_sensitive (default false, a privacy-relevant switch) is never mentioned at all, leaving an agent unable to know sensitive fields can be excluded.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb + resource ('Read one help ticket') with the exact payload enumerated (title, description, unit, category, status, dates, messages, replies, attachments). The phrase 'one ... by numeric ID' functionally distinguishes it from the sibling list tool obs_get_help_tickets, and 'Does not download attachments' scopes it away from download_resource.

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: it is clearly the single-ticket fetch (needing an ID) versus the list sibling, and 'Requires login' gives a prerequisite plus 'Does not download attachments' gives a scope exclusion. But it never explicitly says when to choose this over obs_get_help_tickets or how to obtain the ticket_id.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral detail of which institutional sources are aggregated, but says nothing about freshness, rate limits, or how results are ordered or paged.

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 front-loaded sentence with zero filler; the resource and its sources come first. It is efficient, though the terseness contributes to the parameter gap rather than resolving it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the read-only annotations cover the safety story. The remaining gap is that three undocumented parameters and the absence of any sibling differentiation leave an agent under-equipped 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?

Schema description coverage is 0% for all three parameters, so the description must compensate and largely does not. It hints at the 'sources' parameter by naming the feeds, but 'limit' and 'query' (the filtering and result-count controls) are entirely undocumented anywhere.

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 ('Aggregate') and resource ('official announcements') and enumerates the source feeds (İTÜ, ÖDEK, İKM, SKS, Erasmus), so the agent knows exactly what content it returns. However, it does not distinguish itself from announcement-bearing siblings like get_dashboard_announcements or get_course_announcements, leaving the scope boundary implicit.

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 gives no when-to-use guidance and never references alternatives, even though several sibling tools also surface announcements (get_dashboard_announcements, get_course_announcements, get_updates). The agent must infer that this is the institutional/central feed rather than a course- or dashboard-scoped one.

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