This server connects İTÜ's Ninova LMS and OBS student portal to AI assistants via the Model Context Protocol, enabling natural language access to academic data.
Authentication & Session Management
Check Ninova and OBS authentication status; refresh/create Ninova login sessions
Ninova LMS (requires login)
Dashboard & Courses: Get dashboard summaries, list enrolled courses, retrieve announcements (per-course or dashboard-wide)
Files & Content: List class/lesson files, crawl course pages for resources, download and extract text from PDFs, DOCX, and TXT files
Assignments: View assignment lists and details, check upload slots, and submit files (requires explicit confirmation)
Grades, Attendance & More: Read grades, attendance, message boards, and remote learning pages per course
Sync & Monitoring: Sync all courses, track changes, list upcoming deadlines, snapshot and diff pages over time
Arbitrary Page Reading: Fetch and summarize any authenticated Ninova page (text, headings, links, tables)
OBS Student Portal (requires login)
Profile & Programs: View personal/academic profile (sensitive data redacted by default), list programs and semesters
Courses & Grades: List registered courses per semester, retrieve midterm and letter grades, view attendance records
Schedule & Transcripts: Access weekly class schedule, final exam calendar, and download official transcript PDFs (Turkish or English)
Other: Check registration status, advisor info, internship records, contacts, and graduation requirements/status
OBS Public (no login required)
Search the public course catalog, look up prerequisites, and view public course schedules
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@itu-mcp List my active courses in Ninova"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ninova'da ödev, OBS'de not, Portal'da yemek listesi diye üç ayrı sekmede gezinmek can sıkıcı. İTÜ MCP bilgisayarında çalışan küçük bir sunucu, bu sekmelerin hepsini tek bir yerden, doğal dilde sorulabilir hale getiriyor.
Kimlik bilgilerinle (genelde ad@itu.edu.tr) Ninova, OBS ve Portal verilerini okuyor. Kimlik bilgisi olmadan da ders/final programı, bina kodları, mekik, spor tesisi, duyuru ve kütüphane kataloğu gibi herkese açık kaynaklara erişiyor. Sonuçları Model Context Protocol üzerinden yapılandırılmış araçlar olarak sunuyor: Claude'a soruyorsun, o da gerçek veriyi çekip cevap veriyor.
İhtiyacın | İTÜ MCP cevabı |
"Bu hafta hangi ödevlerin teslimi var?" | Ninova ödev ve teslim tarihi araçları |
"X dersinin notları / yoklaması?" | OBS ara not, harf notu ve yoklama |
"Transkript / danışman / staj?" | OBS profil, danışman, staj, transkript PDF |
"Bugün yemekte ne var / kart bakiyem?" | İTÜ Portal menü, kart ve bildirim araçları |
"Finalim ne zaman / boş kontenjan var mı?" | Public OBS final ve ders programı araçları |
"Mekik ne zaman / havuz kaçta kapanıyor?" | SKS kampüs hizmeti araçları |
"Kütüphanede bu kitap var mı?" | Public katalog arama ve kopya durumu |
"Son okunmamış mailimi göster" | Salt okunur İTÜ Mail araçları |
"PDF özetle" | İndirme ve |
"Ödev yükle" | İsteğe bağlı yükleme, |
Önce yerel. Ninova şifren cihazda kalır, yalnızca İTÜ SSO, Ninova, OBS ve Portal akışlarında kullanılır. Ayrı kütüphane hesabı bilgileri yalnızca resmî kütüphane sunucusuna gönderilir. Üçüncü taraf bir sunucuya kimlik bilgisi depolanmaz.
İTÜ ile resmi bağlantısı yoktur. Yalnızca kendi hesabınla kullan.
Dürüst olmak gerekirse OBS'nin bazı uç noktaları hesaba göre tutarsız davranabiliyor, bir hesapta not alanı boş dönerken başka bir hesapta doluyor gibi. Böyle durumları elimizden geldiğince yakalayıp yedek kaynağa düşüyoruz ve sonucu açıkça işaretliyoruz, ama tam garanti veremeyiz. Şüpheye düştüğünde her zaman OBS'nin kendi sayfasına bak.
Related MCP server: Ninova MCP
graph LR
istemci["Claude, Cursor, Codex"] -->|"MCP"| sunucu["İTÜ MCP"]
sunucu --> ninova["Ninova"]
sunucu --> obs["OBS"]
sunucu --> portal["Portal"]
sunucu --> kutuphane["Kütüphane"]
sunucu --> arsiv["Ders Arşivi"]
sunucu --> mail["İTÜ Mail"]Sunucu her servise ayrı bir istemci sınıfıyla konuşur, kendi oturumunu ve önbelleğini yönetir. Ninova ve OBS aynı İTÜ SSO girişini paylaşır, kütüphane hesabı bilgisi ise tamamen ayrıdır ve Ninova şifresiyle karışmaz. Kimlik gerektirmeyen araçlar (public ders programı, kampüs servisleri, arşiv) hiçbir zaman şifreni kullanmaz.
Ayrıntılı iç mimari ve istemci sınıfları için: docs/advanced.md.
Claude Desktop üzerinden doğal dilde soru sorma örnekleri:
pipx install itu-mcp
# veya: pip install --user itu-mcp
# kaynaktan:
# git clone https://github.com/yatuk/itu-mcp.git
# cd itu-mcp && pip install -e .cp .env.example .env
# NINOVA_USERNAME=ad.soyad@itu.edu.tr
# NINOVA_PASSWORD=********Kullanıcı adı genelde İTÜ e-posta adresidir, yalnızca yerel kısım değil.
itu-mcp --version
itu-mcp --check-auth
itu-mcp --list-tools
itu-mcp --list-promptsClaude Code
claude mcp add itu itu-mcp \
-e NINOVA_USERNAME=ad.soyad@itu.edu.tr \
-e NINOVA_PASSWORD=sifrenCodex CLI
codex mcp add itu \
--env NINOVA_USERNAME=ad.soyad@itu.edu.tr \
--env NINOVA_PASSWORD=sifren \
-- itu-mcpClaude Desktop / Cursor: docs/installation.md ve examples/ klasörüne bak.
Bu kadar. İstemciyi yeniden başlat ve sor: "Ninova'daki derslerimi listele" veya "OBS'te bu dönem kayıtlı derslerim?"
"Bu hafta hangi ödevlerimin teslimi var?"
"EEF 211E sınıf dosyalarındaki PDF'i oku."
"OBS'te 2025-2026 Bahar kayıtlı derslerim neler?"
"CEN 354E ara notlarım?"
"Danışmanım kim? Staj bilgilerimi göster."
"Transkript PDF indir."
"Son okunmamış mesajlarımı listele ve seçtiğim PDF ekini özetle."
"Gelecek dönem hangi dersleri almalıyım?"✨
"Vizeden 63 aldım, sınıf 30,35,40...90 arası dağılmış, hangi harf notunu alırım?"✨
"BLG bölümünde bu dönem hangi dersler açılmış, kontenjan durumu ne?"✨
"BLG 223E'yi almak için önce hangi dersleri almam lazım?"✨
"BBB binası neresi, bugün 10:00'da hangi derslikler boş görünüyor?"✨
"İTÜ mekik saatleri ve yüzme havuzu çalışma saatleri?"✨
"Kütüphanede Introduction to Algorithms var mı?"✨
✨ Kimlik gerektirmez, .env olmadan da çalışır.
Tam araç listesi, hazır prompt'lar, kaynak tabloları, Docker, uzak HTTP ve tüm ortam değişkenleri: docs/advanced.md.
Ayrıca / menüsünden seçilebilen hazır akışlar var (weekly_briefing, plan_next_term, check_course_eligibility, research_course, gpa_scenario), her biri hangi araçların hangi sırayla çağrılacağını ve sonucu okurken kaçırılan kuralları içeriyor.
Kendi hesabını kullanıyorsun, o yüzden şuna dikkat et:
Yap | Yapma |
Yalnızca kendi İTÜ hesabını kullan |
|
Yerel stdio MCP tercih et | Uzak MCP URL / API anahtarını paylaşma |
| Önizlemeyi okumadan ödev yükleme |
Kütüphane PIN'ini ayrı | Ninova şifresini kütüphane PIN'i olarak tekrar kullanma |
Harici sayfa metnini veri olarak değerlendir | Duyuru/ödev metnindeki modele yönelik talimatları uygulama |
Uzak kurulumda | Gizli path ve anahtar olmadan public açma |
Ayrıntılar: docs/security.md. OBS profil araçları TCKN ve telefonu varsayılan olarak gizler (include_sensitive=true ile açılır).
export NINOVA_COURSE_CACHE_TTL_SECONDS=60
export NINOVA_REQUEST_DELAY_MS=120
export NINOVA_SESSION_PERSIST=1
export NINOVA_ALLOW_UPLOADS=1
# Kütüphane hesabı araçları için (public katalog araması bunları istemez):
# NINOVA_LIBRARY_NAME="Soyad, Ad"
# NINOVA_LIBRARY_ID="öğrenci-numarası"
# NINOVA_LIBRARY_PIN="ayrı-kütüphane-pin'i"
# Ayrı mail kimlik bilgisi (yoksa paylaşılan İTÜ kimliği kullanılır):
# NINOVA_MAIL_USERNAME="ad.soyad@itu.edu.tr"
# NINOVA_MAIL_PASSWORD="mail-sifresi"Tüm değişkenler için .env.example ve docs/advanced.md dosyalarına bak.
git clone https://github.com/yatuk/itu-mcp.git
cd itu-mcp
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
pip install -e ".[playwright]"
python -m unittest discover -s tests -vKaynak | URL |
Kurulum | |
Gelişmiş / araçlar | |
Güvenlik | |
Değişiklik günlüğü | |
Sorunlar |
Bu proje, Hikmet Gultekin'in yazdığı orijinal ninova-mcp üzerine kuruldu. İlk açık kaynak, kimlik bilgisiyle çalışan İTÜ Ninova MCP sunucusudur (LMS giriş, HTML ayrıştırma, izleme, .mcpb paketleme).
İTÜ MCP bunun üzerine OBS öğrenci portalı API'lerini, PDF metin okumayı, güvenli ödev yüklemeyi, oturum kalıcılığını, uzak API anahtarını ve arşiv/prompt/resource desteğini ekliyor.
Salt okunur İTÜ Mail araçlarını (mail_status, mail_list_inbox, mail_get_message, mail_get_attachment) tzi4 katkı olarak ekledi, teşekkürler.
MIT. İstanbul Teknik Üniversitesi ile resmi bağlantısı yoktur.
Check whether Ninova credentials are configured and whether a fresh session can be created.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description mentions checking but does not disclose return format, side effects, or error behavior beyond the name.
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?
Single sentence, concise, and front-loaded with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple diagnostic tool with no parameters and an output schema, the description provides adequate context, though it could mention typical usage.
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?
No parameters; schema coverage is 100%; baseline score applies as description adds no parameter info.
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 clearly states the tool checks credential configuration and session creation ability, distinguishing it from siblings like refresh_session.
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 explicit when-to-use or when-not-to-use guidance; usage is implied but not stated, e.g., use before other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check for schedule time conflicts between courses by CRN. Uses the public course schedule to look up session day/time/room.
| Name | Required | Description | Default |
|---|---|---|---|
| crns | Yes | ||
| program_type | No | LS | |
| department_code | No | BLG |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description discloses it uses the public course schedule to look up session day/time/room. It does not explicitly state read-only behavior or side effects, but the output schema and context suggest a non-destructive operation. Adequate but not comprehensive.
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 purpose. No redundant 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?
Given unannotated parameters and existing output schema, the description covers the main functionality but omits details on two optional parameters and does not clarify the return format beyond naming session attributes. Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. The description explains the 'crns' parameter via 'by CRN', but does not mention 'program_type' or 'department_code', leaving their purpose unclear. Insufficient compensation for the lack of schema descriptions.
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 clearly states the tool checks for schedule time conflicts between courses using CRN and sources from the public course schedule. It distinguishes from sibling tools like get_public_course_schedule by focusing on conflict detection.
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 guidance on when to use this tool versus alternatives (e.g., manually checking schedule via get_public_course_schedule). The description implies usage but provides no exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inventory pages and downloadable resources inside a Ninova course tree.
| Name | Required | Description | Default |
|---|---|---|---|
| max_depth | No | ||
| max_pages | No | ||
| course_url | Yes | ||
| include_downloads | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states it inventories pages and downloads but does not specify that it is read-only, whether it recursively traverses, or any other traits like auth requirements or potential performance impact.
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 sentence with no extraneous content. It is front-loaded with the core action and object, earning 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?
Given four parameters, an output schema, and moderate complexity, the minimal description is insufficient. It lacks details on recursive behavior, limits, and output format, which the output schema alone may not fully convey for selection.
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 add meaning. It mentions pages and downloadable resources, which relates to include_downloads, but fails to explain max_depth, max_pages, or course_url format. Two of four parameters are effectively 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?
The description 'Inventory pages and downloadable resources inside a Ninova course tree' uses a specific verb (inventory) and clearly identifies the resource. It distinguishes from sibling tools like read_page and download_resource by indicating a broader scope (crawling the whole tree).
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 guidance is given on when to use this tool vs alternatives like get_course_sections or get_course_lesson_files. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare the current state of a Ninova page against a previously stored snapshot.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| label | No | ||
| snapshot_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states a comparison but omits side effects (likely read-only), error conditions (no snapshot found), or output format. The presence of an output schema mitigates some gaps.
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, concise sentence that front-loads the key purpose. No unnecessary words, but could be slightly more informative without losing 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?
Given the tool has 3 parameters and no schema descriptions, the description is too sparse. It lacks context on how to specify a snapshot (label vs path) and fails to set expectations about required prior actions. Output schema covers return values but not usage flow.
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 explain parameters. It fails to define what 'url', 'label', or 'snapshot_path' mean or how they interact, leaving the agent to guess.
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 clearly identifies the action (compare) and the resources (current state vs stored snapshot), distinguishing it from sibling tools like snapshot_page and read_page. However, it does not specify the nature of the diff output.
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 guidance is given on when to use this tool versus alternatives, prerequisites (e.g., must have a prior snapshot), or when not to use it. Sibling tools exist but are not differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a Ninova file or other authenticated resource to disk.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| filename | No | ||
| output_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions downloading to disk but does not disclose authentication requirements, file overwrite behavior, size limits, or any side effects.
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 concise sentence with no waste, front-loaded with the verb 'Download'.
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 3 parameters, 0% schema coverage, and an output schema not shown, the description fails to provide enough detail for an agent to use the tool correctly. It lacks parameter explanations and behavioral context.
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 adds no meaning to the three parameters (url, filename, output_dir). It does not explain what each parameter does or how to use them.
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 clearly states the action (download), resource (Ninova file or authenticated resource), and destination (to disk). It is specific and distinguishes from siblings like read_page or crawl_course which do not involve downloading to disk.
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 for downloading files but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like crawl_course for other resource types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the İTÜ academic calendar — semester dates, exams, holidays, registration periods (public, no login).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares read-only nature ('Read') and access requirements ('public, no login'), providing key behavioral traits beyond annotations (which are absent). No contradictions.
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?
Single sentence, front-loaded with action and resource, includes all essential details without fluff.
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, read-only tool with an output schema, the description covers purpose, data content, and access, making it 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?
No parameters in schema; baseline 4 applies. Description adds no parameter info, but schema covers 100% with 0 params.
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?
Description clearly states 'Read the İTÜ academic calendar' with specific data items (semester dates, exams, holidays, registration periods) and access status (public, no login). Distinguishes from siblings as no other calendar tool exists.
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 notes 'public, no login', indicating no authentication needed. Does not explicitly state when to use alternatives, but the purpose is clear and no exclusions are necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the file slots on an assignment's 'Ödevi Yükle / OdevGonder' page, including which slots are already filled and allowed extensions.
| Name | Required | Description | Default |
|---|---|---|---|
| course | No | ||
| assignment | No | ||
| upload_url | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavior. It indicates a read operation ('list') but does not explicitly state read-only nature, authentication requirements, or any side effects. The behavioral disclosure is minimal.
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 sentence with no redundant words. It is efficiently structured to convey the main purpose. However, it could incorporate more information without losing 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?
Despite having an output schema (reducing the need to explain return values), the description is too sparse. It fails to clarify how slots are identified, the meaning of 'upload_url', or the behavior when parameters are omitted. Given the tool has three optional parameters and no schema descriptions, the description should provide more context.
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 does not explain the meaning or usage of the three parameters (course, assignment, upload_url). The tool name implies they identify an assignment, but no detail is given on how to provide them or their relationships. This is completely inadequate for an agent to figure out how to populate the parameters.
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 uses a specific verb 'List' and identifies a clear resource 'file slots on an assignment's upload page'. It mentions the included information (filled status, allowed extensions), making the tool's purpose distinct from siblings. However, it does not explicitly differentiate from other tools like 'submit_assignment', so it is not a perfect 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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or cases where another tool should be preferred. The agent has no information about when to choose this over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return announcements for a specific Ninova course.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| course | Yes | ||
| compact | No | ||
| include_full_text | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It does not disclose behavioral traits such as read-only nature, authentication needs, pagination behavior, or side effects. The description is too brief to inform about tool 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 sentence, which is concise, but it sacrifices necessary details. It could benefit from slight expansion for clarity without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not address the four parameters or any usage context. It is too minimal for a tool with 4 parameters and no schema descriptions, leaving significant gaps 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%, and the description fails to explain any parameters (limit, compact, include_full_text). It adds no meaning beyond the raw schema, which is insufficient for an agent to correctly invoke the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it returns announcements for a specific Ninova course, which is clear. However, it does not differentiate from sibling tool get_dashboard_announcements, lacking specificity in scope.
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 guidance is provided on when to use this tool versus alternatives, such as get_dashboard_announcements. There is no mention of prerequisites or context like course enrollment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a course's assignment list. By default also fetches each assignment detail/upload page; set include_details=false for a faster list-only read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| course | Yes | ||
| compact | No | ||
| include_details | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that by default it fetches each assignment detail/upload page, which is a behavioral trait. It also hints at performance implications. No annotations are provided, so the description carries the full burden; it does not discuss auth needs, rate limits, or other side effects, but covers the key default 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 extremely concise with two short sentences. It front-loads the main purpose and adds a useful usage hint without any wasted words. 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?
Despite the presence of an output schema, the description fails to explain key parameters like limit and compact, which are critical for proper usage. Given the tool has 4 parameters and siblings offer similar functionality, the description is insufficiently 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%. The description only explains the include_details parameter and its effect. The required 'course' parameter is implied but not defined, and 'limit' and 'compact' are left entirely undocumented, leaving the agent to guess their meaning.
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 clearly states that the tool returns a course's assignment list, specifying the resource and action. It also mentions the default behavior of fetching details, but does not explicitly differentiate from sibling tools like get_dashboard_assignments.
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 provides guidance on when to set include_details=false for a faster read, which implies when to use the default vs. the opt-out. However, it does not compare this tool to alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the Ninova 'Yoklama' page for a course.
| Name | Required | Description | Default |
|---|---|---|---|
| course | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'Read', implying a non-destructive operation, but it does not disclose any other behavioral traits such as authentication requirements, rate limits, or what happens if the page is inaccessible. The output schema exists but is not detailed in the description.
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 very concise (one sentence) and front-loaded with the key action and resource. However, it is so brief that it omits important context, making it insufficiently 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?
Given the complexity (one parameter, no annotations, 0% schema coverage), the description is incomplete. It lacks usage guidelines, parameter details, and behavioral transparency. The presence of an output schema somewhat mitigates the need to describe return values, but other gaps remain.
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 does not explain the 'course' parameter. It does not specify the expected format (e.g., course ID, course code) or any constraints. The description adds no meaning beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Read' and identifies a clear resource: the Ninova 'Yoklama' page for a course. The tool name 'get_course_attendance' reinforces the purpose, and it is distinguishable from siblings like 'get_course_grades' or 'get_course_assignments'. However, the description does not explicitly differentiate from siblings beyond 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?
No usage guidelines are provided. The description does not specify when to use this tool versus alternatives like 'get_course_overview' or 'get_upcoming_deadlines'. There is no mention of prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and folders under the Ninova 'Sınıf Dosyaları' section for a course.
| Name | Required | Description | Default |
|---|---|---|---|
| course | Yes | ||
| compact | No | ||
| max_depth | No | ||
| recursive | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full responsibility. It only states 'list files and folders', implying a read operation, but lacks any additional behavioral context (e.g., authentication needs, rate limits, or that it is non-destructive).
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?
Extremely concise (single sentence, 13 words). While efficient, the brevity sacrifices necessary details, especially for parameters. It is not bloated but could be more informative without losing 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?
Given the tool has 4 parameters and no annotations or schema descriptions, the description is insufficient. It covers only the basic purpose, leaving out parameter usage, behavioral details, and usage context.
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 explain parameters. It does not mention 'course', 'compact', 'max_depth', or 'recursive' at all. The parameter names provide some hint, but no explicit meaning is added.
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 clearly states the action ('List'), resource ('files and folders'), location ('Ninova 'Sınıf Dosyaları' section'), and scope ('for a course'). It is specific and differentiates from sibling tools like get_course_lesson_files.
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 guidance on when to use this tool versus alternatives. With siblings like get_course_lesson_files, the description should clarify the differences but does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the Ninova 'Notlar' page for a course.
| Name | Required | Description | Default |
|---|---|---|---|
| course | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only says 'Read', implying read-only, but lacks details on authentication, rate limits, or what the page contains. The agent has no insight into behavior beyond 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?
Single sentence with no extraneous words. Front-loaded with verb and resource. Every part 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?
Given an output schema exists and the operation is simple (reading a page), the description is nearly sufficient. It could mention that it retrieves grades specifically, but the tool name implies that. Context is 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?
With 0% schema description coverage, the description adds 'for a course' to the single parameter, providing context that the course identifier is needed. No format or source is specified, but it's minimally informative.
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?
Description clearly states verb 'Read' and resource 'Ninova 'Notlar' page for a course', making it specific and distinct from sibling tools like get_course_assignments or get_course_attendance.
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 guidance on when to use this tool versus alternatives; it only says 'for a course', but doesn't mention prerequisites, when not to use, or how it compares to other get_course_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return structured information from a course's 'Sınıf Bilgileri' page.
| Name | Required | Description | Default |
|---|---|---|---|
| course | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must cover behavioral traits. It only implies a read operation ('Return structured information'), but lacks details on side effects, auth requirements, or performance implications.
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 sentence, but it is under-specified—missing crucial details that a longer description could provide without adding excessive 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?
Despite having an output schema, the description does not explain what the returned structured information contains. Given the many sibling tools, the lack of differentiation and parameter details makes it 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?
The single 'course' parameter has no description in the schema (0% coverage) and the tool description adds no guidance on its format or allowed values.
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 clearly states it returns structured information from a specific page ('Sınıf Bilgileri'). However, it does not differentiate this from other 'get_course_*' siblings, which also return structured data from other pages.
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 guidance on when to use this tool versus alternatives. There is no mention of prerequisites, when-not-to-use, or comparison with similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and folders under the Ninova 'Ders Dosyaları' section for a course.
| Name | Required | Description | Default |
|---|---|---|---|
| course | Yes | ||
| compact | No | ||
| max_depth | No | ||
| recursive | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of disclosing behavioral traits. It only implies a read-only operation ('List') but does not explicitly state that it is non-destructive, requires no special permissions, or that it may involve network access. The description fails to mention pagination, rate limits, or any side effects.
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 sentence that is concise and front-loaded with the action. However, it lacks necessary detail (e.g., parameter descriptions, context) that would make it more useful, so it sacrifices completeness for brevity.
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 the presence of multiple sibling tools and a complex input schema with four parameters, the description is insufficient. It does not explain the meaning of 'Ninova Ders Dosyaları', nor does it hint at the return structure (though an output schema exists). The agent lacks crucial context to use the tool effectively.
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 schema has 0% coverage, meaning no parameter descriptions are provided in the schema. The tool description also offers no explanation of the four parameters ('course', 'compact', 'max_depth', 'recursive'). An agent cannot infer their meaning or defaults from the description alone.
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 clearly states it lists files and folders under a specific section ('Ders Dosyaları') for a course. The verb 'List' is appropriate, and the resource is well-identified. However, it does not explicitly distinguish it from the sibling tool 'get_course_class_files', which might have a similar purpose.
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 provides no guidance on when to use this tool versus alternatives. With siblings like 'get_course_class_files' and 'get_course_sections', an agent would have to infer the appropriate use case from the tool name alone. No context on prerequisites or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the Ninova 'Mesaj Panosu' page for a course.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| course | Yes | ||
| include_thread_details | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Read,' but lacks information on rate limits, required permissions (e.g., course enrollment), pagination, or error behavior. This is inadequate for a tool with three parameters.
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 sentence with no wasted words. However, it sacrifices necessary detail for brevity, so it is not ideally structured for clarity.
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 three parameters with zero schema coverage and no annotations, the description is too minimal. An output schema exists, but an agent still needs parameter context and usage details to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate by explaining parameters like 'limit' and 'include_thread_details.' It does not; only the field names are given, adding no semantic value.
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 clearly states the verb 'Read' and the specific resource 'Ninova 'Mesaj Panosu' page for a course.' This distinguishes it from sibling tools like get_course_announcements, but it could be more precise about the content type (e.g., messages, threads).
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 guidance is provided on when to use this tool versus alternatives, nor any prerequisites or scenarios where it should not be used. The description only states what it does.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a combined view of a course's sections, announcements, assignments, files, grades, message board, attendance, and remote learning routes.
| Name | Required | Description | Default |
|---|---|---|---|
| course | Yes | ||
| compact | No | ||
| refresh | No | ||
| file_max_depth | No | ||
| include_assignment_details | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks behavioral details such as data freshness, performance implications, or whether it aggregates live data. It only describes the output content.
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, focused sentence that clearly communicates the tool's purpose. However, it could be slightly more efficient by not listing all components individually, but it remains concise.
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?
Despite having an output schema (which may explain return values), the description fails to cover parameter usage or behavioral context. Given the tool's complexity and lack of annotations, it 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?
Schema coverage is 0%, so the description must explain parameters, but it does not. Parameter names like 'compact' and 'refresh' suggest control over output, but no clarification is given. The description adds no value beyond 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?
The description clearly states the tool returns a combined view of various course components (sections, announcements, assignments, etc.), distinguishing it from sibling tools that focus on individual aspects.
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 this tool is for when a comprehensive overview is needed, but does not explicitly state when to use it over individual get_course_* tools or any when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the Ninova 'Uzaktan Eğitim' page for a course.
| Name | Required | Description | Default |
|---|---|---|---|
| course | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation but does not disclose additional behavioral traits such as return format, authentication requirements, or pagination. No annotations are present to compensate.
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 very concise (one sentence), but it is not front-loaded with key information. It could be more efficient while still being 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?
While the tool has an output schema, the description lacks essential context such as what the page contains, any prerequisites, or differentiation from other tools. Incomplete for a tool with 25 siblings.
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 parameter 'course' is only implicitly mentioned in the description ('for a course'), adding no meaning beyond the parameter name. Schema coverage is 0%, so the description should provide more context.
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 clearly states it reads a specific page ('Uzaktan Eğitim') for a course, which is distinct from other course tools. However, it could be more specific about what this page contains.
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 guidance on when to use this tool versus alternatives like get_course_info or get_course_sections. With many similar siblings, explicit differentiation is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return all courses visible in the Ninova dashboard (alias of list_courses).
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only states it returns courses and is an alias, but does not mention authentication needs, side effects (none expected), rate limits, or caching behavior implied by the refresh parameter.
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 sentence that efficiently conveys the tool's purpose and equivalence to list_courses. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, output schema exists), the description is partially complete. It covers purpose but omits parameter behavior, which is a significant gap for a complete understanding.
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 description does not mention any parameters, leaving the refresh parameter's purpose unexplained. With 0% schema description coverage, the description fails to add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'all courses visible in the Ninova dashboard'. It also distinguishes itself by noting it is an alias of list_courses, which prevents confusion with sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it is an alias of list_courses, providing some guidance on tool equivalence, but it does not give explicit when-to-use or when-not-to-use instructions, nor does it discuss the refresh parameter's purpose or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the direct course routes exposed on the Ninova course home page.
| Name | Required | Description | Default |
|---|---|---|---|
| course | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like read-only nature, authentication requirements, or side effects. It only states it lists routes, leaving important behavioral context unaddressed.
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, efficient sentence that front-loads the core purpose. However, it could benefit from additional structure or clarification without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of many sibling tools and an output schema, the description lacks completeness. It does not explain what 'direct course routes' entails or describe the output shape, limiting the agent's ability to use the tool effectively.
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%, meaning the description adds no meaning to the single 'course' parameter. The schema defines it as a required string, but without any context about expected format or values, the description fails to compensate.
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 uses a specific verb ('List') and resource ('direct course routes exposed on the Ninova course home page'), clearly distinguishing it from sibling tools that retrieve other course data like grades or announcements. However, the term 'direct course routes' is slightly vague.
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 guidance is provided on when to use this tool versus siblings such as get_course_overview or get_course_info. The description does not mention prerequisites, context, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the Ninova dashboard and summarize courses, recent announcements, assignments, and messages.
| Name | Required | Description | Default |
|---|---|---|---|
| compact | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description labels the operation as 'Read', implying non-destructive behavior. However, with no annotations, it misses the chance to disclose traits like authentication requirements, what happens on empty data, or whether it combines multiple sources. It is adequate but lacks explicit behavioral details beyond the verb.
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 concise sentence of 14 words, front-loaded with the action and resource. However, it could be structured to include parameter details. It achieves brevity without waste, but misses the opportunity to be more informative due to 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?
Given the low complexity (one optional param, output schema exists), the description should cover output nature and how 'compact' affects it. It does not mention output at all and omits parameter semantics, leaving a significant gap in context completeness.
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' is described only in the schema (boolean, default false). The description provides no explanation of its purpose or effect, leaving the agent to guess. With 0% schema description coverage, the description should compensate but fails entirely.
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 clearly states the tool reads the Ninova dashboard and summarizes courses, announcements, assignments, and messages. The verb 'Read' indicates read-only access, and the resource is the dashboard. It differentiates from sibling tools like get_dashboard_announcements or get_dashboard_assignments by offering a combined summary, though 'summarize' could be more precise.
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 guidance is provided on when to use this tool versus alternatives. Siblings like get_dashboard_announcements or get_dashboard_assignments exist for specific data, but the description doesn't advise using this tool for an overview or when to drill down. This leaves the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the announcements listed under the Ninova dashboard's aggregated announcements page.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| include_full_text | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides minimal behavioral insight. It states 'Return' implying a read operation but does not mention authentication requirements, rate limits, pagination, or any side effects.
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 sentence, which is concise, but it omits crucial information about parameters and usage. It could be improved with additional context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (not shown), the description is insufficient. It does not explain the scope of the announcements, what 'aggregated' means, or how parameters affect the result. The context is incomplete for effective use.
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%, meaning the input schema lacks descriptions. The tool description does not mention the 'limit' or 'include_full_text' parameters at all, so it adds no meaning beyond their names and types.
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 clearly states the verb 'Return' and the resource 'announcements from the Ninova dashboard's aggregated announcements page'. It distinguishes from sibling tools like 'get_course_announcements' by specifying the dashboard context.
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 guidance is given on when to use this tool versus alternatives such as 'get_course_announcements' or 'get_dashboard_assignments'. The description lacks any context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the assignments listed under the Ninova dashboard's aggregated assignments page. Set include_details=false for a faster list-only read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| include_details | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It reveals the read-only nature and a performance trade-off, but does not disclose potential issues like rate limits, pagination, or authorization requirements. The output schema exists, so return details are not needed 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?
Two sentences with no wasted words. The first sentence immediately states the purpose, and the second provides a key usage tip. Front-loads essential information efficiently.
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 the existence of sibling tools and an output schema, the description is otherwise complete. It covers the core functionality and an optimization flag. Could briefly note that it aggregates across courses, but 'aggregated dashboard page' implies this.
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 compensate. It explains the 'include_details' parameter's effect on performance, adding value beyond the schema's boolean type. However, the 'limit' parameter is not described, leaving a gap. Partial compensation for one of two parameters.
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 clearly states the action ('Return') and specific resource ('assignments listed under the Ninova dashboard's aggregated assignments page'). It distinguishes from sibling tools like 'get_course_assignments' (per-course) and 'get_dashboard_announcements' (different content type).
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 provides a performance optimization tip ('Set include_details=false for a faster list-only read'), but does not explicitly compare this tool to siblings or state when not to use it. The context hints at dashboard vs course-level distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read prerequisite details from a course's public OBS DersBilgi page. No login required. Returns structured prerequisite list with codes, names, groups, and types.
| Name | Required | Description | Default |
|---|---|---|---|
| ders_no | Yes | ||
| brans_kodu | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It states the operation is a read from a public page with no login, which implies safety. However, it does not describe error conditions or what happens if the page is inaccessible.
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 extremely concise with two sentences that convey essential information without redundancy or 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?
Given the presence of an output schema, the description appropriately summarizes return fields. It covers the tool's purpose and key constraints (public, no login), but lacks parameter details, which is a minor gap for a simple 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%, yet the description does not explain the parameters 'brans_kodu' and 'ders_no' beyond their titles. The tool context suggests they identify a course, but no explicit definition is given, leaving agents to infer meaning.
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 clearly states the tool reads prerequisite details from a public course page, specifies the output includes structured data like codes, names, groups, and types, and distinguishes it from sibling tools like obs_get_course_prerequisites that require authentication.
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 mentions 'No login required,' which guides usage for public data access. Implicitly distinguishes from authenticated prerequisite tools, but could more directly state alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the public OBS course schedule for a department. No login required — reads the open DersProgram page. Returns structured course list with CRN, instructor, sessions (day/time/room), capacity, enrolled count, and prerequisite links.
| Name | Required | Description | Default |
|---|---|---|---|
| crn | No | ||
| program_type | Yes | ||
| department_code | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the tool is read-only and requires no login, which covers safety and authentication. However, it does not mention potential rate limits or error conditions, which would add completeness.
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 concise sentences with no fluff. The first sentence is front-loaded with the core purpose, and the second adds relevant detail. Every word 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?
Given that an output schema exists, the description needn't detail return values; it still mentions key fields (CRN, instructor, sessions, capacity, enrolled count, prerequisite links). It is adequate for a simple fetch tool, though it could note any semester constraints or result limits.
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 clarifies the department_code parameter by mentioning 'for a department' and implies crn via output fields, but does not explain program_type. This adds partial meaning but not full coverage for all three parameters.
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 clearly states the verb 'Read', the resource 'public OBS course schedule', and the scope 'for a department'. It distinguishes from siblings by emphasizing 'No login required' and 'public', making its purpose 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?
The description implies usage context (retrieving public schedule without authentication) but does not explicitly mention when not to use it or provide alternatives like get_public_course_prerequisites or get_course_info. No exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return assignments whose submission deadline is approaching based on the stored tracking snapshot.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| refresh | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. It mentions relying on a snapshot but doesn't disclose staleness, read-only nature, or effect of the 'refresh' parameter.
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, 14 words, concise. But lacks structure or additional detail that would improve clarity.
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?
Despite having output schema, the description omits critical context: how the snapshot is used, when to refresh, and differentiation from get_course_assignments or get_dashboard_assignments.
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%. The description does not explain what 'days' or 'refresh' do, leaving the agent to infer from names only.
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 clearly states it returns assignments with upcoming deadlines, distinguishing it from siblings like get_course_assignments. However, 'based on the stored tracking snapshot' is vague.
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 guidance on when to use this tool versus siblings or prerequisites like taking a snapshot first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the stored Ninova tracking history and return recent detected changes.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| course | No | ||
| entity_type | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read operation but does not disclose any behavioral traits such as auth requirements, rate limits, pagination, or what 'recent' means. With no annotations, the description should provide more detail.
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, concise sentence without fluff, but it lacks structure (e.g., bullet points) and is too brief to be fully 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?
Given the 3 optional parameters and existence of an output schema, the description is insufficient. It does not explain filtering behavior or return format, making it incomplete for a tool that likely queries a history log.
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%, meaning the parameters are entirely undocumented. The description does not explain 'limit', 'course', or 'entity_type' or how they affect results, leaving the agent without critical usage details.
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 clearly states the tool reads 'stored Ninova tracking history' and returns 'recent detected changes', which identifies it as a read-only retrieval tool. It uses specific verbs and resource naming, differentiating it from sibling tools like crawl_course (which likely fetches fresh data).
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 guidance is provided on when to use this tool versus alternatives. Given the many sibling tools (e.g., get_dashboard, get_course_info), the description offers no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all discovered Ninova courses from the dashboard (TTL-cached).
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds valuable behavioral context by noting TTL-caching, indicating data may be stale. However, it doesn't describe behavior when refresh parameter is true.
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?
Single sentence, front-loaded with key information, no redundancy. Every word serves a purpose.
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 listing tool with output schema, the description covers purpose and caching. Missing details on refresh behavior and pagination, but not critical.
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 'refresh' is not explained in the description. Despite schema coverage being 0%, the parameter name is intuitive, but the description adds no extra meaning.
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 clearly specifies the action (list), resource (courses), source (dashboard), and caching behavior (TTL-cached). It distinguishes from siblings like sync_all_courses and get_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?
The description implies usage for quick listing via dashboard cache but lacks explicit guidance on when to use vs alternatives like get_courses or sync_all_courses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether an OBS JWT can be obtained with the configured İTÜ credentials.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden of disclosure. It only says 'check whether a JWT can be obtained', but does not specify what happens in failure cases, side effects, or security implications. This is insufficient for a tool that likely interacts with authentication.
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, clear sentence with no extraneous information. Every word is necessary and well-placed.
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 0-parameter tool with an output schema, the description is nearly complete. However, it could briefly mention the return type (e.g., boolean) to improve usability, but this is not critical.
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 input schema has no parameters (0 params), so the description does not need to add parameter semantics. The baseline is 4; the description adds context about the check's purpose, which is meaningful beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('check') and resource ('whether an OBS JWT can be obtained'), making the purpose clear. However, it does not differentiate from the similarly named sibling 'auth_status', which could cause confusion.
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 provides no guidance on when to use this tool versus alternatives (e.g., auth_status), no prerequisites, and no conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate GPA/GANO from OBS registered courses. Supports projected grades for what-if scenarios. Uses İTÜ 4.00-scale letter grade conversion.
| Name | Required | Description | Default |
|---|---|---|---|
| semester | No | ||
| projected_grades | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains core behavior but doesn't disclose side effects, authentication needs, or rate limits.
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 efficiently convey purpose, what-if support, and grade scale. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the main function is clear and output schema exists, the semester parameter's role (filtering vs cumulative) is not explained, leaving some ambiguity.
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 compensate. It explains projected_grades for what-if scenarios but does not detail the format or explain the semester parameter.
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 clearly states the tool calculates GPA/GANO from OBS registered courses using a specific scale, with a distinct purpose among siblings like obs_get_course_grades.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: calculate GPA from registered courses with what-if scenarios, but no explicit exclusion or alternative tools mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download OBS transcript preview PDF to the local state downloads folder.
| Name | Required | Description | Default |
|---|---|---|---|
| english | No | ||
| output_dir | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits like side effects, authentication needs, or whether it overwrites files. It only states the basic download action without any such disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, but it is too short and omits important information. It does not earn its place given the missing parameter explanations and behavioral context.
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 the two parameters and output schema, the description is incomplete. It lacks explanation of the english flag and output_dir, and does not clarify what the output schema contains. The tool's complexity is low, but the description still fails to cover key aspects.
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 does not explain the parameters (english, output_dir) at all. It fails to add meaning beyond the schema's type constraints.
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 clearly states the action (Download), resource (OBS transcript preview PDF), and destination (local state downloads folder). It is specific and distinguishes from sibling tools like download_resource, but 'local state downloads folder' is vague and not explained.
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 guidance on when to use this tool versus alternatives (e.g., download_resource). No prerequisites or exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read academic advisor information from OBS.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description offers no behavioral details beyond the basic read operation. It fails to disclose authentication needs, data freshness, or what 'advisor information' 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?
The description is a single, concise sentence that conveys the core purpose without any unnecessary words. It is optimally front-loaded.
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 the simplicity (no parameters, output schema exists), the description is minimally adequate. However, it would benefit from specifying what aspects of advisor information are returned or any limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters (empty input schema), so the description naturally cannot add meaning beyond the schema. Baseline of 4 is appropriate since no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Read' and clearly identifies the resource 'academic advisor information from OBS.' It effectively differentiates from sibling tools by specifying 'advisor,' which is unique among the many obs_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like obs_get_contacts or obs_get_profile. The description does not mention any context or prerequisites for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read attendance for an OBS class. Includes computed absence-risk summary by default.
| Name | Required | Description | Default |
|---|---|---|---|
| course | No | ||
| class_id | No | ||
| semester | No | ||
| include_summary | No | ||
| max_absence_ratio | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions that the tool includes a computed absence-risk summary by default, hinting at its behavior. However, it does not state whether the tool is read-only, or disclose any side effects or required permissions.
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 very short (two sentences) and front-loaded with the core action. It is efficient, but could add a bit more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is too thin for a tool with 5 parameters. It fails to explain how course, class_id, and semester affect results, or how the absence-risk is computed. The tool is incomplete for effective use.
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, but it provides no explanation of any parameter. The 'include_summary' and 'max_absence_ratio' are referenced implicitly ('by default'), but their meanings are unclear. Users must rely on the schema field titles, which are minimal.
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 clearly states the tool reads attendance for an OBS class, differentiating it from sibling 'get_course_attendance' by the 'OBS' prefix. However, it assumes the user knows what OBS refers to, which could be clarified.
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 guidance on when to use this tool versus alternatives like get_course_attendance or other attendance tools. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read campus card balance and recent transactions from OBS (requires login).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description declares read behavior and login requirement. Could detail output format or error handling, but adequate for a simple operation.
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?
Single sentence that is front-loaded with action and includes key prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and existence of output schema, description covers purpose and prerequisite. Could specify 'recent transactions' range, but overall 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?
Zero parameters; baseline is 4 per guidelines. Description adds value by explaining the resource, but no param details needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Read', resource 'campus card balance and recent transactions', and scope 'from OBS'. Distinct from sibling tools like obs_get_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies prerequisite 'requires login' and implies read-only use. No explicit when-not or alternative guidance, but context is clear for a 0-param tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read İTÜ Mail and İTÜ Bulut storage quota from the Portal (requires login).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits beyond being a read operation. It lacks details on idempotency, side effects, or error conditions.
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 conveys the essential purpose and a key prerequisite without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and zero parameters, the description is largely complete. It could be slightly more specific about what quota attributes are retrieved, but the output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema coverage. The description adds no parameter information, which is acceptable for a parameterless tool, earning the baseline score of 4.
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 clearly states the specific action (Read) and the resource (İTÜ Mail and İTÜ Bulut storage quota from the Portal). It is distinct from sibling tools which cover different data types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is 'requires login', which is a precondition. No explicit instructions on when to use this tool versus similar read tools, and no exclusion scenarios are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read contact records from OBS (phones/emails redacted by default).
| Name | Required | Description | Default |
|---|---|---|---|
| include_sensitive | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It usefully discloses that sensitive data is redacted by default, a behavioral trait. However, it omits other behaviors like read-only nature (implied but not explicit), authentication requirements, or rate limits.
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, efficient sentence with no wasted words. All information is front-loaded and relevant.
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 description is very brief but the tool is simple. An output schema exists, reducing the need to explain return values. However, it lacks context on when to use this tool (e.g., for viewing contacts) and does not mention pagination or ordering, which might be relevant for a contact 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?
There is one parameter ('include_sensitive') with 0% schema coverage. The description indirectly explains its purpose by stating the default redaction, implying that include_sensitive=true would show redacted data. However, it does not explicitly name the parameter or describe its effect in detail.
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 clearly states the verb 'Read', the resource 'contact records', and a key behavioral detail ('phones/emails redacted by default'). It effectively distinguishes from sibling tools, none of which are contact-specific.
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 explicit guidance on when to use this tool versus alternatives. No mention of when-not-to-use or related tools, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read midterm and/or letter grades for an OBS class (by sinifId or course code).
| Name | Required | Description | Default |
|---|---|---|---|
| course | No | ||
| class_id | No | ||
| semester | No | ||
| include_letter | No | ||
| include_midterms | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It declares a read operation, which is consistent with the tool name. However, it does not disclose additional behavioral traits like response format, pagination, or potential limitations, leaving some uncertainty.
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, efficient sentence with no unnecessary words, front-loading the action and parameters. It is well-structured for quick comprehension, though it could be slightly more informative without losing 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?
Given the tool has five optional parameters and an output schema, the description provides a high-level summary but omits details on the return value and semantics of unmentioned parameters. It is sufficient for a simple read tool but has notable gaps.
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 description adds meaning for two of five parameters by mentioning identification by sinifId (class_id) or course code (course). The other parameters (semester, include_letter, include_midterms) are not explained. With 0% schema coverage, this partial elucidation is helpful but incomplete.
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 clearly states the tool reads midterm and/or letter grades for an OBS class, specifying the identification methods (by sinifId or course code). It distinguishes from sibling tools like 'get_course_grades' by the OBS prefix and the explicit mention of grade types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as the similar 'get_course_grades'. No context about prerequisites, exclusions, or preferred use cases is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query prerequisite and postrequisite relationships for a course from the OBS public catalog. Supports chain queries up to 10 levels deep.
| Name | Required | Description | Default |
|---|---|---|---|
| direction | No | prerequisites | |
| max_depth | No | ||
| course_code | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses a behavioral trait: chain queries up to 10 levels deep. However, it omits other traits like read-only nature, rate limits, or data freshness.
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 concise sentences with no wasted words. Purpose is front-loaded, and key feature (chain depth) is included.
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 query tool with an output schema (present), the description is fairly complete: states resource, relationships, and depth limit. Missing details like direction default and depth range, but output schema may cover return structure.
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%. The description hints at 'course_code' and 'direction' (prerequisite/postrequisite) and 'max_depth' (up to 10 levels), but does not fully explain defaults or allowed values. Minimal added value over schema 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?
Description clearly states the tool queries prerequisite/postrequisite relationships for a course from the OBS public catalog, and distinguishes itself with chain query support. The verb 'query' and resource 'OBS public catalog' are specific.
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?
Description implies usage for exploring course relationships but does not explicitly state when to use vs. alternatives like get_public_course_prerequisites or other course info tools. No exclusions or when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read 'mezuniyetime ne kaldı', academic status, and debts for a program.
| Name | Required | Description | Default |
|---|---|---|---|
| program_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only says 'Read', implying a safe operation, but does not disclose any potential side effects, authentication requirements, rate limits, or return characteristics. For a read tool, this minimal transparency is insufficient.
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 sentence with no wasted words, but it is under-specified. A concise description should still convey essential details; here, it achieves conciseness at the expense of completeness.
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?
Despite having an output schema, the tool's description fails to cover parameter semantics and usage context. It does not state what the output contains or how to interpret results. The tool is complex (multiple outputs: graduation remaining, status, debts) but the description provides minimal 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?
The only parameter, program_id, has 0% schema description coverage. The description does not explain what a program_id is, how to obtain it, or its relationship to the output. The agent is left to guess its meaning beyond the schema's type and default null.
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 clearly states the verb 'Read' and the resources: graduation remaining, academic status, and debts. It specifies the scope 'for a program', which differentiates it from other OBS tools that read different aspects (e.g., advisor, attendance). The title and name align well.
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 guidance on when to use this tool versus alternative OBS tools. Given the large number of sibling tools with similar prefixes, the agent needs explicit context on when to select this over obs_get_advisor, obs_get_registration_status, etc. The description provides no such guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read İTÜ Portal help desk tickets (requires login).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only notes the login requirement, but does not disclose read-only nature, output details, or other behaviors (e.g., pagination, filtering). This is insufficient for a tool with no 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?
The description is a single sentence with no unnecessary words. However, it is quite brief for a tool with no annotations; slightly more context (e.g., what the output looks like) would improve completeness without sacrificing 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?
Given 0 parameters and an output schema that the agent can access, the description does not need to explain return values. However, the tool has no annotations, so the description should provide more behavioral context. The login requirement is mentioned, but overall it feels minimal for a tool with no structured metadata.
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 input schema has 0 parameters, and schema description coverage is 100% (vacuously). The description does not need to add any parameter details, as there are none. The requirement 'requires login' is an environmental condition, not a parameter.
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 clearly states the tool reads help desk tickets from the İTÜ Portal. The verb 'Read' and resource 'help desk tickets' are specific and unambiguous. Among many sibling tools, none are related to help tickets, so it is well-distinguished.
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 mentions 'requires login' but does not specify when to use this tool versus alternatives or when not to use it. It implies usage for reading tickets, but no explicit guidance or exclusions are provided. Sibling tools do not cover help tickets, so no alternative is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read internship records from OBS.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Read', implying a safe, idempotent operation, but does not disclose any other behavioral traits like data recency, role requirements, or rate limits.
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 extremely concise, one sentence with no fluff. However, it is so terse that it misses opportunities to add value without losing 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?
Given the tool has no parameters and an output schema exists, the description is minimally adequate. It fails to provide any context about the source (OBS), scope, or typical use cases, leaving gaps in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100% trivially. The description adds meaning by specifying 'internship records', which gives context to the empty input. Baseline for zero params is 4, and the description meets that.
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 clearly states the verb 'Read' and resource 'internship records from OBS', distinguishing it from sibling tools that read other resources (e.g., advisor, attendance). It is specific and 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?
The description provides no information on when to use this tool versus alternatives, nor any context about prerequisites or limitations. The purpose is clear, but guidance on usage is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read İTÜ Portal notifications (requires login).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only discloses the login requirement, but fails to mention other behavioral traits such as whether it is read-only, what happens on authentication failure, or the scope of notifications. This is minimal for a tool with no 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?
The description is a single concise sentence that front-loads the core purpose. Every word earns its place with no 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?
Given the tool's simplicity (no parameters) and the existence of an output schema, the description is adequate but lacks detail about what notifications are returned (e.g., all vs. recent, from which system). It meets the minimum but does not fully exploit the opportunity to provide helpful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description does not need to add parameter semantics beyond the schema. It correctly omits any parameter details, as there are none to document.
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 clearly states the action ('Read') and resource ('İTÜ Portal notifications'), aligning perfectly with the tool name and title. Among siblings, there is no other notification tool, so it is well-distinguished.
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 mentions 'requires login' as a prerequisite, but provides no explicit guidance on when to use this tool versus alternatives or when not to use it. Usage is implied: use when you need to read notifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read OBS personal/program profile. Sensitive fields are redacted unless include_sensitive=true.
| Name | Required | Description | Default |
|---|---|---|---|
| include_sensitive | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses redaction behavior for sensitive fields and the effect of the 'include_sensitive' parameter. However, with no annotations provided, it omits other behavioral traits such as authentication requirements, error handling, or rate limits, making coverage partial.
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 sentence with no wasted words. It front-loads the core action ('Read OBS personal/program profile') and concisely adds the key behavioral note about sensitive fields.
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 the presence of an output schema (covering return values) and the tool's simplicity (one optional boolean parameter), the description sufficiently covers the essential behavior. It could optionally list what fields constitute the profile, but the current level is adequate for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'include_sensitive' has zero schema description coverage, so the description carries the full burden. It effectively explains that setting it to true avoids redaction of sensitive fields, adding clear meaning beyond the bare schema definition.
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 clearly states the verb 'Read' and the resource 'OBS personal/program profile', making the tool's purpose unambiguous. It distinguishes itself from sibling tools like obs_get_advisor or obs_get_attendance, which target different specific data.
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 guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, use cases, or exclusion criteria, leaving the agent to infer appropriate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read OBS registration and course-registration status (active/class level).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden of behavioral disclosure. It only states it 'reads' status, but does not mention authentication requirements, data freshness, potential side effects (none expected), or any other behavioral traits. For a read-only tool with no annotations, the description is insufficient on safety and prerequisites.
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?
Single, front-loaded sentence that immediately communicates the action and resource. No extraneous words or structure.
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 the tool has no parameters, an output schema exists (though not described), and the description covers the core purpose. It could be improved by noting that no arguments are needed, but it is largely complete for a simple read-only 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?
No parameters exist, so schema coverage is effectively 100%. The description adds no parameter information, but none is needed. Per guidelines, 0 parameters yields a baseline of 4, and the description meets that baseline by not introducing confusion.
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?
Description explicitly states 'Read OBS registration and course-registration status (active/class level)'. The verb 'Read' indicates a safe query operation, and the specific resource ('OBS registration and course-registration status') with a hint of the returned data ('active/class level') clearly distinguishes it from sibling tools like obs_auth_status (auth status) or obs_get_profile (profile info).
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 guidance on when to use this tool versus alternatives. With multiple OBS tools (e.g., obs_list_registered_courses, obs_auth_status), the description does not specify that this is for checking active registration status as opposed to listing registered courses or verifying authentication. Provides no context for when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read weekly class schedule and final exam calendar for a semester.
| Name | Required | Description | Default |
|---|---|---|---|
| semester | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states 'Read' indicating a read-only operation, but lacks details on semester parameter behavior (e.g., default value handling), rate limits, or any side effects. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, but it lacks necessary details about parameters and behavior. Under-specification reduces usability despite being short.
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 the tool has an output schema, the description should clarify the input and output semantics. It mentions 'weekly class schedule and final exam calendar' but does not explain the semester parameter or what the output contains. Incomplete for a query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description should compensate for the single parameter 'semester'. It does not explain acceptable values, format (e.g., '2024-1'), or behavior when null. No added meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a weekly class schedule and final exam calendar for a semester. It uses a specific verb 'Read' and specifies the resource, distinguishing it from sibling tools like obs_get_attendance or obs_get_course_grades.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool over alternatives. While the purpose is clear, there are no when/when-not statements or comparisons to siblings like obs_get_attendance or obs_get_course_grades. Usage is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the student's OBS academic programs (e.g. undergraduate major).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only says 'List', implying read-only, but lacks details on authentication needs, rate limits, or any side effects. For a simple read tool, this minimal disclosure is acceptable but not thorough.
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 short sentence that is front-loaded and concise. Every word adds value; no extraneous text.
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 the tool's simplicity (no parameters, output schema exists), the description is adequate. It clearly states what the tool does. However, it could briefly mention what fields or info are returned, but the output schema covers that. So it's slightly above minimum.
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 input schema has zero parameters, so there is nothing to add beyond schema. With 100% schema coverage (no parameters) and no enums, the description correctly does not need to compensate. A baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the specific resource 'student's OBS academic programs' with an example 'undergraduate major'. It is unambiguous and distinguishes this tool from siblings like obs_get_profile or obs_list_registered_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?
The description implies usage for listing programs but does not provide explicit guidance on when to use this tool versus alternatives (e.g., other OBS tools like obs_get_profile). No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List courses registered in OBS for a semester (default: latest).
| Name | Required | Description | Default |
|---|---|---|---|
| semester | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose that this is a read-only operation, any authentication requirements, or potential side effects. For a simple list tool, stating read-only would improve transparency.
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 wasted words. It efficiently conveys the tool's primary action and default behavior.
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 the presence of an output schema and a single optional parameter, the description is largely complete. It covers the key aspect of selecting a semester, though it could mention the output format or edge cases like empty results.
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 input schema lacks descriptions (0% coverage), so the tool description bears the full burden. It explains the 'semester' parameter and its default behavior ('default: latest'), adding meaningful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'courses registered in OBS', and distinguishes from sibling tools like obs_list_programs and obs_list_semesters by specifying 'for a semester'.
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 when to use the tool (listing registered courses) but lacks explicit guidance on when not to use it or alternatives. The default semester behavior is noted, but no exclusions or preconditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List academic semesters available in OBS for the student.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as authentication requirements, data source, or any side effects. As a read-only list, it is minimally transparent.
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 wasted words. It efficiently conveys the tool's purpose.
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 the tool has no parameters and an output schema exists, the description is adequate but could be improved by noting its role relative to other OBS tools (e.g., prerequisite for enrollment).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds no extra parameter info, but with zero parameters, it meets the baseline of 4.
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 clearly states the action (list) and resource (academic semesters), distinguishing it from siblings like obs_get_schedule or obs_list_programs. It is specific and 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 guidance on when to use this tool versus alternatives. For example, it does not mention that this is a prerequisite for other OBS operations or contrast with obs_get_schedule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the public OBS course catalog by code or name (no auth required).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that no authentication is required, which is a key behavioral trait. However, does not mention rate limits, pagination, or what happens on no results. With no annotations, more detail would be beneficial.
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?
Single sentence, concise, front-loaded with verb and resource. Could be slightly more structured but is clear and efficient.
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?
Adequate for a simple tool with output schema present. Covers purpose and a behavioral trait, but lacks parameter details for limit. Overall sufficient but not thorough.
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 description mentions 'code or name' which relates to the query parameter, but does not explain format or that limit is available. With 0% schema description coverage, the description should provide more parameter guidance.
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?
Clearly states the verb 'search', resource 'public OBS course catalog', and criteria 'by code or name'. Distinguishes from sibling tools like list_courses or get_course_info which are for different purposes.
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?
Implicitly tells when to use: when searching by code or name. No explicit exclusions or alternatives, but the context of 'public' and 'no auth' sets it apart from authenticated course tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch any Ninova page and return a structured summary of text, headings, links, tables, and attachments.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| compact | No | ||
| link_limit | No | ||
| include_text | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only indicates a read operation returning a structured summary, but it does not mention authentication, rate limits, error handling, or side effects. This is insufficient for safe invocation.
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 sentence that is concise and front-loaded, but it sacrifices necessary detail. It is efficient but incomplete given the tool's complexity and sibling context.
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 the tool has four parameters, no schema descriptions, no annotations, and many siblings, the description is too sparse. It does not explain parameter usage or distinguish from similar tools, leaving significant gaps despite an existing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no explanation for any of the four parameters (url, compact, link_limit, include_text). The agent must infer their meaning from names alone, which is inadequate.
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 clearly states the tool fetches any Ninova page and returns a structured summary, specifying content types (text, headings, links, tables, attachments). It is clear and uses a specific verb+resource construct, but it does not explicitly distinguish itself from siblings such as snapshot_page or read_resource_text.
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 guidance is provided on when to use this tool versus alternatives like get_course_info or read_resource_text. There is no statement of context, prerequisites, or exclusions, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract plain text from a Ninova PDF/DOCX/TXT (or a local path from download_resource) so the assistant can read lecture notes and assignments.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| path | No | ||
| filename | No | ||
| max_chars | No | ||
| save_download | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states 'Extract plain text' but lacks details on whether the tool is read-only, if it modifies files, or the impact of parameters like 'max_chars' and 'save_download'.
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, concise sentence that front-loads the action and purpose without extraneous 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?
Despite having an output schema, the description is insufficient for a 5-parameter tool with no annotations. It omits behavioral details and parameter roles, leaving the agent with incomplete 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?
The description adds value by explaining 'url' and 'path' as sources (Ninova URLs or local paths from download_resource), but with 0% schema coverage, it fails to clarify other parameters like 'filename', 'max_chars', and 'save_download'.
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 clearly states the action ('Extract plain text') and the resource type ('Ninova PDF/DOCX/TXT or a local path from download_resource'), differentiating it from sibling tools like 'read_page' and '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?
The description implies usage for reading lecture notes and assignments but does not explicitly state when to use or avoid this tool compared to alternatives like 'download_resource' or 'read_page'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force a new login with NINOVA_USERNAME and NINOVA_PASSWORD.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It says 'force a new login' but doesn't explain side effects (e.g., overwriting existing sessions), required permissions, or error conditions.
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?
Single, concise sentence with no unnecessary words. It is front-loaded and efficiently communicates the core action.
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 has an output schema (not shown) but the description omits what the output represents (e.g., success message, new token). It also doesn't mention prerequisites like setting environment variables, leaving gaps for an AI 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?
Input schema has no parameters (100% coverage). The description adds meaning by specifying that the tool uses NINOVA_USERNAME and NINOVA_PASSWORD from the environment, which goes beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'force a new login' and identifies the resources (NINOVA_USERNAME and NINOVA_PASSWORD). It effectively distinguishes from sibling tools like 'auth_status' and other read-only tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., checking auth_status first). No mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a structured snapshot of a Ninova page for later comparison.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| label | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions 'structured snapshot' but does not explain what 'structured' entails, whether the snapshot is stored permanently, if it overwrites previous snapshots, or any side effects. For a mutation tool, critical behavioral traits are missing.
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 concise sentence that immediately conveys the core purpose. It is front-loaded and efficient, but could include more detail without becoming bloated.
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 the tool's apparent complexity (saving a structured snapshot), the description is too brief. It does not mention the return value, page requirements, or limitations. The presence of an output schema is not acknowledged, leaving the agent with insufficient context 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%, yet the description adds no information about the two parameters ('url' and 'label'). It does not clarify what values they accept, their purpose, or how they affect the tool's behavior. This is a significant 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 clearly states the action ('Save'), the resource ('structured snapshot of a Ninova page'), and the purpose ('for later comparison'). It distinguishes from siblings like 'read_page' and 'diff_snapshot' by specifying the snapshotting and comparison use case.
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 when a permanent snapshot is needed for comparison, but does not explicitly state when to use this tool versus alternatives like 'read_page' or 'diff_snapshot'. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a local file to one Ninova assignment slot via the official multipart form. Requires confirm=true to actually post; without it, returns a dry-run preview only. Ask the user before confirming.
| Name | Required | Description | Default |
|---|---|---|---|
| course | No | ||
| confirm | No | ||
| file_path | Yes | ||
| assignment | No | ||
| slot_index | No | ||
| upload_url | No | ||
| allow_replace | No | ||
| slot_description | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses the dry-run mode and confirmation requirement but omits details like error handling, file size limits, or behavior when replacing files. Sensible but not exhaustive.
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: first defines purpose and method, second explains the critical confirm behavior and user instruction. No superfluous words, front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and 0% schema coverage, the description should compensate but only covers two parameters. The output schema exists but the description doesn't leverage it. Lacks completeness for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description only explains confirm and implicitly file_path. The other six parameters (course, assignment, slot_index, upload_url, allow_replace, slot_description) are not mentioned, leaving the agent without guidance on their usage.
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 clearly states the action ('Upload a local file'), resource ('Ninova assignment slot'), and method ('official multipart form'). It distinguishes from sibling tools like get_assignment_upload_slots which retrieve slots.
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 states the need for confirm=true for actual posting vs. dry-run preview, and instructs to ask user before confirming. However, it does not mention when to use this tool vs. alternatives like download_resource or read_page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch all visible courses, store a tracking snapshot, and return newly detected changes since the previous sync. Assignment detail pages are skipped by default for speed.
| Name | Required | Description | Default |
|---|---|---|---|
| course_limit | No | ||
| include_files | No | ||
| file_max_depth | No | ||
| include_assignment_details | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses the core action (fetch, store, return changes) and a default behavior, but omits side effects like state modification, required permissions, and rate limits. It does not contradict any 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?
Two efficient sentences. The first front-loads the main function; the second adds a key default. No unnecessary 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?
Given the tool's complexity (sync with snapshot) and 4 parameters, the description is brief. It covers the core purpose and a default, but does not explain parameters or the snapshot statefulness. Output schema existence partially compensates for return value details.
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%, yet the description adds no explicit parameter explanations. Only a vague reference to 'assignment detail pages' links to include_assignment_details, but course_limit, include_files, and file_max_depth are unmentioned. The description fails to compensate for the lack of schema descriptions.
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 clearly states the tool fetches all visible courses, stores a snapshot, and returns changes, distinguishing it from siblings like get_courses or crawl_course. It also mentions a notable default behavior (skipping assignment details).
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 hints at when to include assignment details for speed, but does not explicitly guide when to use this tool versus alternatives like get_courses or diff_snapshot. No prerequisites or when-not scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.3check_course_conflictsget_academic_calendarget_cafeteria_menuget_public_course_prerequisitesget_public_course_scheduleobs_calculate_gpaobs_get_attendance2 fields changedInput schema / properties / include_summaryAdded value: +{
+ "default": true,
+ "title": "Include Summary",
+ "type": "boolean"
+}Input schema / properties / max_absence_ratioAdded value: +{
+ "default": 0.3,
+ "title": "Max Absence Ratio",
+ "type": "number"
+}obs_get_campus_cardobs_get_cloud_quotaobs_get_course_prerequisitesobs_get_help_ticketsobs_get_notificationsobs_search_coursesv0.2.0auth_statuscrawl_coursediff_snapshotdownload_resourceget_assignment_upload_slotsget_course_announcementsget_course_assignmentsget_course_attendanceget_course_class_filesget_course_gradesget_course_infoget_course_lesson_filesget_course_message_boardget_course_overviewget_course_remote_learningget_course_sectionsget_coursesget_dashboardget_dashboard_announcementsget_dashboard_assignmentsget_upcoming_deadlinesget_updateslist_coursesobs_auth_statusobs_download_transcriptobs_get_advisorobs_get_attendanceobs_get_contactsobs_get_course_gradesobs_get_graduation_remainingobs_get_internshipsobs_get_profileobs_get_registration_statusobs_get_scheduleobs_list_programsobs_list_registered_coursesobs_list_semestersread_pageread_resource_textrefresh_sessionsnapshot_pagesubmit_assignmentsync_all_coursesScored across 55 tools
Most tools have distinct purposes, with clear separation between Ninova and OBS systems. A few aliases (get_courses/list_courses) and overlapping assignment/grade tools exist, but descriptions clarify context.
All tool names follow a consistent verb_noun pattern in snake_case, with clear prefixes (auth_, check_, get_, obs_, etc.). No mixing of conventions.
55 tools is high, but the server covers two comprehensive systems (Ninova LMS and OBS student info). The count is borderline heavy but still reasonable for the scope.
The tool set covers nearly every aspect of a student's interaction with the university portal: courses, assignments, grades, attendance, files, calendar, registration, GPA, transcript, etc. No obvious gaps.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Brazilian Open Finance MCP — 30+ banks (Itaú, Nubank, etc.) to Claude/Cursor. Read-only.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
