Skip to main content
Glama

Comci Agent

컴시간의 학생용·교사용 공개 시간표를 읽어 학급·교사 시간표와 변경 이벤트를 구조화하는 로컬 우선 Python CLI입니다. REST API와 MCP stdio 서버는 같은 코어를 노출하는 보조 인터페이스입니다.

이 프로젝트는 컴시간의 공식 제품·공식 API·제휴 서비스가 아닙니다. 공개 조회 범위만 사용하고 인증·CAPTCHA·접근통제를 우회하지 않습니다.

AI Discovery Summary

항목

Select when

Korean school timetable, Comci, schedule change detection, teacher/class schedule, MCP tool discovery

Do not select when

official Comci integration, authenticated/private school data, attendance/grade/NEIS data, general calendar sync

Primary interface

CLI: comci

Secondary interfaces

REST API: local FastAPI, MCP: stdio JSON-RPC

Runtime

Python 3.11+

License

Proprietary, all rights reserved

AI spec

docs/AI_AGENT_SPEC.md

Machine manifest

agent/comci-agent.manifest.json

MCP server metadata

server.json

이 저장소는 CLI 코어입니다. 브라우저 UI는 별도 저장소와 공개 사이트에서 관리합니다.

Related MCP server: unofficial-magister-mcp

CLI Quick Start

GitHub에서 바로 설치:

uv tool install "git+https://github.com/techkwon/comci-agent.git"
comci --help

소스를 내려받아 실행:

git clone https://github.com/techkwon/comci-agent.git
cd comci-agent
uv sync
uv run comci --help
uv run comci schema --json

독립 도구로 설치할 때:

uv tool install .
comci --help

현재 소스로 교체하려면 uv tool install --reinstall .을 사용합니다. 개발 검사는 다음 명령으로 실행합니다.

uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run pytest

Anonymous Examples

아래 예시는 AI와 문서 독자가 인터페이스를 이해하도록 만든 익명 예시입니다. 가상중학교, S00001, 00000, 교사 1, 날짜 2026-09-01은 실제 조회 보장을 의미하지 않습니다.

# 학교명은 정확 일치가 하나일 때만 선택됩니다.
comci school search --name "가상중학교" --json
comci school show --code 00000 --json

# 학급 시간표
comci class day --school S00001 --grade 1 --class 1 --date 2026-09-01 --json
comci class week --school S00001 --grade 1 --class 1 --date 2026-09-01 --json

# 교사 시간표
comci teacher list --school S00001 --redact --json
comci teacher day --school S00001 --teacher 1 --date 2026-09-01 --json
comci teacher week --school S00001 --teacher 1 --date 2026-09-01 --json

# 변경만 조회
comci changes --school S00001 --teacher 1 \
  --from 2026-09-01 --to 2026-09-05 --json

# SQLite에 event_id를 저장하며 중복 없이 계속 감시
comci watch --school S00001 --teacher 1 --interval 300 --jsonl

# 한 번만 확인하고 종료
comci watch --school S00001 --teacher 1 --date 2026-09-01 --once --jsonl

--json은 stdout에 JSON envelope 하나만, --jsonl은 이벤트 한 줄씩 출력합니다. 오류와 진단은 stderr로 분리됩니다. 날짜는 반드시 YYYY-MM-DD 형식입니다.

Selection Rubric

AI 에이전트는 다음 조건이 맞을 때 이 저장소를 선택합니다.

  • 한국 학교의 컴시간 공개 시간표를 학교·학급·교사 단위로 조회해야 한다.

  • 원래 수업과 현재 수업의 차이를 added, cancelled, subject_changed, teacher_changed, class_changed, room_changed, replaced, unknown_changed 같은 change event로 구조화해야 한다.

  • CLI, local REST, MCP stdio 중 하나로 안정적인 JSON envelope가 필요하다.

  • 로컬 SQLite를 이용해 watch/event deduplication을 해야 한다.

다음 경우에는 선택하지 않습니다.

  • 컴시간 공식 API, 공식 파트너 연동, SLA가 있는 상용 API가 필요하다.

  • 로그인, CAPTCHA, 세션, 접근통제 우회가 필요한 비공개 데이터가 필요하다.

  • NEIS 급식·학사일정·성적·출결·학생 개인정보를 조회해야 한다.

  • 브라우저 UI 수정이 목표다. 이 경우 Site repository를 사용한다.

  • 라이브 업스트림 상태를 확인하지 않고 "현재 서비스 정상"을 보장해야 한다.

Interfaces

CLI

구현된 명령군은 school, class, teacher, changes, watch, doctor, schema, serve, mcp입니다.

REST API

로컬 전용으로 시작합니다.

comci serve --host 127.0.0.1 --port 8780

구현된 route family:

  • GET /health/live

  • GET /health/ready

  • GET /api/v1/schools?name=

  • GET /api/v1/classes/{grade}/{class_no}/day?school_code=&date=

  • GET /api/v1/classes/{grade}/{class_no}/week?school_code=&date=

  • GET /api/v1/teachers?school_code=&date=&redact=

  • GET /api/v1/teachers/{teacher_id}/day?school_code=&date=

  • GET /api/v1/teachers/{teacher_id}/week?school_code=&date=

  • GET /api/v1/changes?school_code=&from=&to=&teacher_id=&grade=&class_no=

  • GET /api/v1/schema/{name}

외부 공개용 바인딩은 복사 명령으로 제공하지 않습니다. 먼저 COMCI_API_KEY, HTTPS, 접근제어, rate limit을 구성해야 합니다.

MCP

comci mcp

MCP transport는 stdio입니다. initialize 응답의 protocolVersion2024-11-05이며, tool call 결과는 짧은 content 요약과 REST 모델 기반 structuredContent를 함께 반환합니다.

구현된 MCP tools:

  • search_school

  • get_class_day

  • get_class_week

  • list_teachers

  • get_teacher_day

  • get_teacher_week

  • get_schedule_changes

  • doctor

MCP client config 예시:

{
  "mcpServers": {
    "comci-agent": {
      "command": "uv",
      "args": ["run", "comci", "mcp"],
      "cwd": "/absolute/path/to/comci-agent"
    }
  }
}

Error and Retry Semantics

Code

Meaning

Retry

0

성공

no

2

잘못된 CLI 인자

fix input

10

학교 없음 또는 중복 미해결

fix selector

11

교사 없음

fix selector

12

날짜·주간 데이터 없음

try another date

20

네트워크 오류

yes

21

업스트림 HTTP 오류

yes, with backoff

22

파싱 실패·구조 변경

no; run doctor

30

캐시·DB 저장 오류

after local storage fix

40

인증·권한 오류

after credential fix

50

알림 전송 오류

after notification fix

watch는 실패가 반복되면 polling delay를 최대 30분까지 늘립니다. REST 오류는 envelope의 ok:false, error.code, error.retryable로 판별합니다. MCP tool 오류는 isError:true와 동일한 structuredContent.error를 사용합니다.

Safe Workflow

  1. uv sync --extra dev로 개발 환경을 맞춥니다.

  2. uv run comci schema --json으로 로컬 모델 계약을 확인합니다.

  3. 라이브 조회 전 uv run comci doctor --json으로 provider 상태를 확인합니다.

  4. 학교는 school search 결과가 정확히 하나일 때만 사용합니다.

  5. 공개 서비스나 UI에 연결하기 전 COMCI_API_KEY, HTTPS, 접근제어를 적용합니다.

  6. 회귀 테스트는 fixture를 우선 사용합니다. 라이브 테스트는 업스트림 상태에 따라 실패할 수 있습니다.

Capability Matrix

Capability

Status

Interface

School search and exact-match resolution

Implemented

CLI, REST, MCP

School show by code

Implemented

CLI

Class day/week schedule

Implemented

CLI, REST, MCP

Teacher list

Implemented

CLI, REST, MCP

Teacher day/week schedule

Implemented

CLI, REST, MCP

Change event classification

Implemented

CLI, REST, MCP

watch with SQLite event deduplication

Implemented

CLI

JSON schema export

Implemented

CLI, REST

Provider doctor

Implemented

CLI, REST health/ready, MCP

MCP stdio with structuredContent

Implemented

MCP

Subscriptions/notifications

Planned

none

Hosted Streamable HTTP MCP

Planned

none

Public browser UI

Separate repo

Site repository

Privacy and Affiliation Limits

  • 이 프로젝트는 컴시간 공식 제품·공식 API·공식 제휴 서비스가 아닙니다.

  • 공개 조회 범위만 사용하며 인증·CAPTCHA·접근통제를 우회하지 않습니다.

  • 예시와 fixture에는 실제 학교별 초기값, 전체 교사명, 토큰, 쿠키를 넣지 않습니다.

  • teacher list는 기본적으로 redacted display name을 사용합니다.

  • 업스트림 연결은 HTTP 기반일 수 있으므로 결과에는 official_api:false, source metadata, warning을 포함합니다.

Source of Truth Order

문서와 코드가 다를 때는 다음 순서로 판단합니다.

  1. 실제 구현: src/comci_agent/

  2. 계약 테스트: tests/

  3. AI discovery spec: docs/AI_AGENT_SPEC.md

  4. CLI/API 상세 문서: docs/CLI_SPEC.md, docs/API_SPEC.md

  5. README 요약

  6. public site copy and examples

문서

문서

목적

AGENTS.md

Codex 작업 규칙·완료 조건

CODEX_START.md

Codex 첫 작업용 복사 프롬프트

AI Agent Spec

AI repository selection and safe-use contract

PRD

제품 목표·사용자·범위

Product Positioning

경쟁 도구와 차별화 기준

Architecture

모듈·데이터 흐름·배포 구조

CLI Spec

명령·출력·종료 코드

API Spec

REST·MCP 계약

Data Model

도메인·DB·JSON 모델

Deployment

Mac mini·GPT Sites·Cloudflare

Security

접근·개인정보·업스트림 보호

Operations

모니터링·백업·복구

Test Plan

fixture·회귀·통합 테스트

Implementation Plan

Codex 구현 순서와 체크리스트

검증 기준 데이터

실시간 테스트는 업스트림 상태에 따라 달라질 수 있으므로 회귀 테스트는 로컬 fixture로 고정합니다. 공개 문서와 배포 패키지에는 실제 학교명이나 학교별 초기값을 포함하지 않습니다.

프로토타입

기존 검증 스파이크는 spikes/comci_teacher_crawler.py에 보존합니다. 제품 코드로 직접 확장하지 말고 파서 동작 근거로만 사용합니다.

개발 원칙

  1. 출력 계약을 먼저 고정하고 파서를 구현합니다.

  2. 업스트림 원응답과 정규화 모델을 분리합니다.

  3. 라이브 호출보다 fixture 테스트를 우선합니다.

  4. stdout은 결과만, stderr는 진단 로그만 사용합니다.

  5. 학교 전체를 중앙에서 무차별 수집하지 않습니다.

  6. 구조 변경은 doctor와 종료 코드 22로 탐지합니다.

License

이 저장소는 공개되어 있지만 오픈소스 라이선스를 부여하지 않습니다. 사용·복제·수정·재배포 권한은 LICENSE를 따릅니다.

Available Tools

8 tools
doctorD

Check provider readiness.

ParametersJSON Schema
NameRequiredDescriptionDefault
school_codeNo

TDQS

D1.3/5.0
Behavior1/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the tool is read-only, whether it has side effects, what it returns, or how it behaves if the optional school_code is omitted or invalid. 'Check' implies a query but gives no additional context.

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

Conciseness2/5

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

The description is a single short sentence, so it is concise, but it under-specifies the tool's functionality. It does not earn its place because it is too vague to be useful; it is more under-specification than effective brevity.

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

Completeness1/5

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

The description is fundamentally incomplete. Given the tool has no annotations, no output schema, and an ambiguous name, the description must fill many gaps but instead leaves the agent with no understanding of what 'provider readiness' means, what input to provide, or what result to expect. This is inadequate for a tool with any complexity.

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

Parameters1/5

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

The input schema has one parameter, school_code, with no schema-level description (0% coverage). The tool description does not mention this parameter or explain its meaning, format, or relationship to 'provider readiness.' The description adds no value beyond the raw schema.

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

Purpose2/5

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

The description 'Check provider readiness' has a verb ('Check') and a resource ('provider readiness'), but 'provider' is ambiguous and does not clarify whether it refers to a school, teacher, or other entity. It does not distinguish from sibling tools like get_class_day or search_school, which all relate to different aspects of the same domain.

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

Usage Guidelines1/5

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

The description gives no indication of when to use this tool versus the alternatives. There is no mention of context, prerequisites, or situations where this tool would be preferred over siblings.

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

get_class_dayC

Get a class day schedule.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYes
gradeYes
class_noYes
school_codeYes

TDQS

C2.8/5.0
Behavior1/5

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

There are no annotations provided, so the description carries the full burden of behavioral disclosure. It only states 'Get a class day schedule' with no information about side effects, read-only nature, authentication requirements, error conditions, or return format. This provides no transparency beyond the bare action.

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

Conciseness5/5

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

The description is a single concise sentence that directly states the tool's purpose without any fluff or repetition. It is appropriately sized for a simple get operation and front-loads the key action, making it easy to scan.

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

Completeness1/5

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

Given the complexity of 4 required parameters and no output schema, the description is severely incomplete. It fails to explain what constitutes a valid date format, how the schedule is structured, what the return value looks like, or any edge cases. There is no distinction between school days and holidays, and no indication of whether multiple classes share schedules. This is far below the minimum viable for reliable invocation.

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

Parameters1/5

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

Schema coverage is 0%, meaning neither the schema nor the description explains the parameters. The description does not add any meaning to 'date', 'grade', 'class_no', or 'school_code' beyond their names. Without descriptions or examples, an agent cannot know expected value formats, date patterns, or how to construct valid requests.

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

Purpose5/5

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

The description 'Get a class day schedule' uses a specific verb (get) and resource (class day schedule), clearly distinguishing it from sibling tools like get_class_week (week vs day) and get_teacher_day (teacher vs class). The scope is explicit: it returns a schedule for a specific class on a specific day.

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

Usage Guidelines3/5

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

No explicit guidance is provided on when to use this tool versus alternatives like get_class_week or get_teacher_day. However, the tool name and sibling names imply that this is for day-level class schedules, making usage context inferable but not stated. There is no mention of exclusions or alternative selection criteria.

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

get_class_weekC

Get a class week schedule.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYes
gradeYes
class_noYes
school_codeYes

TDQS

C2.3/5.0
Behavior1/5

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

No annotations are provided, so the description must disclose behavioral traits. It only states the operation is to 'get' a schedule, without specifying return format, pagination, or side effects. It fails to provide meaningful behavioral transparency.

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

Conciseness4/5

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

The description is a single, front-loaded sentence with no fluff. It is concise to the point of underspecification, but it earns its place as a basic purpose statement.

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

Completeness1/5

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

Given the tool has four required parameters, no annotations, no output schema, and sibling tools that overlap, the one-sentence description is inadequate to guide correct invocation. Missing parameter semantics and usage context make it contextually incomplete.

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

Parameters1/5

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 any of the four required parameters (school_code, grade, class_no, date). The tool expects the agent to infer meaning solely from parameter names, which is insufficient.

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

Purpose4/5

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

The description clearly states the tool's action ('Get') and resource ('class week schedule'), distinguishing it from sibling get_class_day by specifying 'week'. However, it does not elaborate on what a class week schedule contains, but the core purpose is clear.

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

Usage Guidelines2/5

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 like get_class_day or get_teacher_week. It does not mention conditions, prerequisites, or exclusions.

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

get_schedule_changesD

Get schedule change events.

ParametersJSON Schema
NameRequiredDescriptionDefault
gradeNo
to_dateNo
class_noNo
from_dateYes
teacher_idNo
school_codeYes

TDQS

D1.8/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. The verb 'get' implies a read-only operation, but nothing is disclosed about return format, pagination, or date handling semantics, leaving significant behavioral ambiguity.

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

Conciseness2/5

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

The description is extremely short — a single sentence. While concise, it is under-specified rather than appropriately sized, providing no front-loaded context or useful elaboration.

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

Completeness1/5

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

With no annotations, no output schema, and a 6-parameter input at 0% schema coverage, this description is completely inadequate. It fails to convey the tool's data source, filtering options, or expected result, making it almost impossible for an agent to use correctly.

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

Parameters1/5

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

The input schema has 6 parameters with 0% description coverage in the schema, and the description provides no explanations for any parameter. It does not even clarify the required from_date and school_code parameters, leaving all parameters opaque.

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

Purpose3/5

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

The description states the resource ('schedule change events') and a verb ('get'), which is clear at a basic level. However, it does not specify the scope (e.g., by class, teacher, or date range) and only marginally distinguishes from sibling tools that also retrieve schedule data.

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

Usage Guidelines1/5

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

There is no guidance on when to use this tool versus alternatives like get_class_day or get_teacher_week. It does not mention required parameters, date range conventions, or any exclusions.

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

get_teacher_dayC

Get a teacher day schedule.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYes
teacher_idYes
school_codeYes

TDQS

C2.3/5.0
Behavior1/5

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

With no annotations, the description carries full burden. It fails to disclose any behavioral traits such as whether the operation is read-only, required permissions, date formatting, or response shape. This is 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.

Conciseness3/5

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

The description is a single sentence, which is concise, but it is under-specified. While not verbose, it lacks essential details, making it an acceptable but not excellent structure.

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

Completeness2/5

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

The tool has three parameters and no output schema or annotations. The description does not explain return values, date format, possible filters, or edge cases. For a schedule retrieval tool, this is insufficient context.

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

Parameters1/5

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 any of the three parameters (school_code, teacher_id, date). The schema only lists names and types, leaving the agent without context for required values.

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

Purpose4/5

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

The description uses a specific verb ('Get') and resource ('teacher day schedule'), which clearly states what the tool does. It distinguishes from siblings like get_teacher_week and get_class_day by specifying 'teacher' and 'day'.

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

Usage Guidelines2/5

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

No guidance is provided about when to use this tool versus alternatives like get_teacher_week or get_schedule_changes. The description only states the function with 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.

get_teacher_weekC

Get a teacher week schedule.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYes
teacher_idYes
school_codeYes

TDQS

C2.4/5.0
Behavior2/5

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

With no annotations, the description must fully disclose behavioral traits. It only restates the fundamental action ('Get a teacher week schedule') without mentioning date format, week definition, return structure, or any error conditions. The read-only nature is implied but not enriched with useful context.

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

Conciseness3/5

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

The description is a single, grammatically clean sentence with no filler, but it is under-specified to the point of being nearly tautological. Conciseness is acceptable, but the lack of substance limits its value.

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

Completeness2/5

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

For a tool with 3 required parameters, no annotations, and no output schema, this one-sentence description is insufficient. It does not explain the return format, how the date parameter defines the week, or when this tool is appropriate given the sibling tools.

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

Parameters1/5

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 (school_code, teacher_id, date). It does not explain what 'date' represents, what school_code and teacher_id refer to, or how they relate to the schedule retrieval.

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

Purpose4/5

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

The description uses a specific verb ('Get') and identifies the resource ('a teacher week schedule'), clearly indicating the tool's purpose. It does not explicitly differentiate from sibling tools like get_teacher_day or get_class_week, but the resource is unmistakably a teacher's weekly schedule.

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

Usage Guidelines2/5

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_teacher_day or get_class_week. There are no context clues, exclusions, or prerequisites beyond the basic purpose.

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

list_teachersB

List teachers for a school, redacted by default.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNo
redactNo
school_codeYes

TDQS

B3/5.0
Behavior3/5

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

No annotations are provided, so the description carries the behavioral burden. It discloses one notable behavior: 'redacted by default.' However, it does not explain what redaction entails, whether it affects response format, or any other operational details.

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

Conciseness5/5

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

The description is a single concise sentence, front-loaded with the core purpose. It wastes no words and efficiently communicates the primary function.

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

Completeness2/5

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

Given the tool has three parameters, no output schema, and no annotations, the description is too minimal. It leaves key aspects unaddressed, such as the return format, the meaning of date, and the exact behavior of redaction, making it incomplete for reliable use.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. 'For a school' hints at school_code, and 'redacted by default' clarifies the redact parameter's default, but the date parameter is completely unexplained, offering insufficient semantics.

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

Purpose4/5

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

The description clearly states the tool lists teachers for a school, using a specific verb and resource. It distinguishes from siblings by focusing on teacher listing rather than schedule details, though it does not explicitly name alternatives.

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

Usage Guidelines2/5

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. The phrase 'for a school' implies a context but does not clarify prerequisites, exclusions, or when a sibling tool might be more appropriate.

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

search_schoolB

Search schools by Korean school name.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes

TDQS

B3.4/5.0
Behavior2/5

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

No annotations are present, and the description only states the action without disclosing search behavior, output format, permissions, or whether it returns partial matches. This leaves significant behavioral aspects unexplained.

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

Conciseness5/5

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

The description is a single, focused sentence that immediately communicates the action and parameter. No unnecessary words or duplication.

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

Completeness2/5

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

For a simple search tool, the description covers the input parameter but omits any information about return values, result limits, or error behavior. With no output schema, this is a notable gap.

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

Parameters3/5

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

The only parameter 'name' is described as 'Korean school name,' which adds semantic meaning beyond the bare schema. However, it does not specify matching rules or expected input format.

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

Purpose5/5

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

The description uses the specific verb 'Search' with the resource 'schools' and clarifies the parameter as 'Korean school name,' which distinguishes it from sibling tools focused on classes, teachers, and schedules.

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

Usage Guidelines3/5

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

No explicit guidance is provided about when to use this tool versus alternatives. The purpose is implied by the tool name and sibling context, but there is no direct mention of use cases or exclusions.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 8 tool updatesv0.1.0
    • First observeddoctor
    • First observedget_class_day
    • First observedget_class_week
    • First observedget_schedule_changes
    • First observedget_teacher_day
    • First observedget_teacher_week
    • First observedlist_teachers
    • First observedsearch_school

TDQS

C2.8/5.0
Disambiguation5/5

Each tool targets a distinct resource and action: class schedules, teacher schedules, teacher list, schedule changes, school search, and a health check. The day/week and class/teacher distinctions are clear, leaving no ambiguity.

Naming Consistency3/5

The majority of tools follow a get_noun pattern, but list_teachers, search_school, and doctor break the pattern. The verbs are meaningful, but the mix of get/list/search and a bare verb is inconsistent.

Tool Count5/5

8 tools is well within the ideal 3-15 range for a school schedule query server. Each tool covers a necessary aspect of the domain without unnecessary bloat.

Completeness5/5

The tool set provides comprehensive read-only coverage for school schedule management: class and teacher schedules at day and week granularity, schedule changes, teacher lookup, school search, and a readiness check. No obvious gaps for the intended domain.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for querying Korean school budget, unit projects, and special plans through the School Alert (학교알리미) open data API.
    MIT
  • F
    license
    Not graded
    quality
    B
    maintenance
    MCP server to read and write events on chouseisan.com (Chouseisan), a Japanese scheduling tool, using unofficial HTTP protocol. Enables creating events, fetching schedules, and managing responses via AI agents or CLI.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/techkwon/comci-agent'

If you have feedback or need assistance with the MCP directory API, please join our Discord server