comci-agent
Click on "Install 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., "@comci-agentShow me today's timetable for class 1-1"
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.
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: |
Secondary interfaces | REST API: local FastAPI, MCP: stdio JSON-RPC |
Runtime | Python 3.11+ |
License | Proprietary, all rights reserved |
AI spec | |
Machine manifest | |
MCP server metadata |
이 저장소는 CLI 코어입니다. 브라우저 UI는 별도 저장소와 공개 사이트에서 관리합니다.
Public site: https://comci-agent-timetable-20260807.techkwon.chatgpt.site/
Site repository: https://github.com/techkwon/comci-agent-sites-ui
CLI/source repository: https://github.com/techkwon/comci-agent
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 pytestAnonymous 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/liveGET /health/readyGET /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 mcpMCP transport는 stdio입니다. initialize 응답의 protocolVersion은 2024-11-05이며, tool call 결과는 짧은 content 요약과 REST 모델 기반 structuredContent를 함께 반환합니다.
구현된 MCP tools:
search_schoolget_class_dayget_class_weeklist_teachersget_teacher_dayget_teacher_weekget_schedule_changesdoctor
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 |
| 성공 | no |
| 잘못된 CLI 인자 | fix input |
| 학교 없음 또는 중복 미해결 | fix selector |
| 교사 없음 | fix selector |
| 날짜·주간 데이터 없음 | try another date |
| 네트워크 오류 | yes |
| 업스트림 HTTP 오류 | yes, with backoff |
| 파싱 실패·구조 변경 | no; run |
| 캐시·DB 저장 오류 | after local storage fix |
| 인증·권한 오류 | after credential fix |
| 알림 전송 오류 | after notification fix |
watch는 실패가 반복되면 polling delay를 최대 30분까지 늘립니다. REST 오류는 envelope의 ok:false, error.code, error.retryable로 판별합니다. MCP tool 오류는 isError:true와 동일한 structuredContent.error를 사용합니다.
Safe Workflow
uv sync --extra dev로 개발 환경을 맞춥니다.uv run comci schema --json으로 로컬 모델 계약을 확인합니다.라이브 조회 전
uv run comci doctor --json으로 provider 상태를 확인합니다.학교는
school search결과가 정확히 하나일 때만 사용합니다.공개 서비스나 UI에 연결하기 전
COMCI_API_KEY, HTTPS, 접근제어를 적용합니다.회귀 테스트는 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 |
| Implemented | CLI |
JSON schema export | Implemented | CLI, REST |
Provider | Implemented | CLI, REST health/ready, MCP |
MCP stdio with | 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
문서와 코드가 다를 때는 다음 순서로 판단합니다.
실제 구현:
src/comci_agent/계약 테스트:
tests/AI discovery spec:
docs/AI_AGENT_SPEC.mdCLI/API 상세 문서:
docs/CLI_SPEC.md,docs/API_SPEC.mdREADME 요약
public site copy and examples
문서
문서 | 목적 |
Codex 작업 규칙·완료 조건 | |
Codex 첫 작업용 복사 프롬프트 | |
AI repository selection and safe-use contract | |
제품 목표·사용자·범위 | |
경쟁 도구와 차별화 기준 | |
모듈·데이터 흐름·배포 구조 | |
명령·출력·종료 코드 | |
REST·MCP 계약 | |
도메인·DB·JSON 모델 | |
Mac mini·GPT Sites·Cloudflare | |
접근·개인정보·업스트림 보호 | |
모니터링·백업·복구 | |
fixture·회귀·통합 테스트 | |
Codex 구현 순서와 체크리스트 |
검증 기준 데이터
실시간 테스트는 업스트림 상태에 따라 달라질 수 있으므로 회귀 테스트는 로컬 fixture로 고정합니다. 공개 문서와 배포 패키지에는 실제 학교명이나 학교별 초기값을 포함하지 않습니다.
프로토타입
기존 검증 스파이크는 spikes/comci_teacher_crawler.py에 보존합니다. 제품 코드로 직접 확장하지 말고 파서 동작 근거로만 사용합니다.
개발 원칙
출력 계약을 먼저 고정하고 파서를 구현합니다.
업스트림 원응답과 정규화 모델을 분리합니다.
라이브 호출보다 fixture 테스트를 우선합니다.
stdout은 결과만, stderr는 진단 로그만 사용합니다.
학교 전체를 중앙에서 무차별 수집하지 않습니다.
구조 변경은
doctor와 종료 코드22로 탐지합니다.
License
이 저장소는 공개되어 있지만 오픈소스 라이선스를 부여하지 않습니다. 사용·복제·수정·재배포 권한은 LICENSE를 따릅니다.
Available Tools
8 toolsdoctorD
Check provider readiness.
| Name | Required | Description | Default |
|---|---|---|---|
| school_code | No |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| grade | Yes | ||
| class_no | Yes | ||
| school_code | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| grade | Yes | ||
| class_no | Yes | ||
| school_code | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| grade | No | ||
| to_date | No | ||
| class_no | No | ||
| from_date | Yes | ||
| teacher_id | No | ||
| school_code | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| teacher_id | Yes | ||
| school_code | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| teacher_id | Yes | ||
| school_code | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | ||
| redact | No | ||
| school_code | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
TDQS
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.
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.
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.
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.
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.
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.
8 tool updates
v0.1.0- First observed
doctor - First observed
get_class_day - First observed
get_class_week - First observed
get_schedule_changes - First observed
get_teacher_day - First observed
get_teacher_week - First observed
list_teachers - First observed
search_school
TDQS
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.
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.
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.
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
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
MCP server providing attendance data queries via the CloudTime API.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
An MCP server that provides congressional transcripts
MCP server for China Railway 12306 ticket availability: schedules and seats by Chinese station name.
21
Related MCP Servers
- FlicenseAqualityDmaintenanceA simple MCP server for event scheduling and automation.12-
- AlicenseAqualityDmaintenanceAn MCP server for accessing Dutch school schedules from Magister. Enables Claude and other MCP-compatible AI assistants to query school schedules, drop-off times, and pick-up times.4153MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for querying Korean school budget, unit projects, and special plans through the School Alert (학교알리미) open data API.MIT
- FlicenseNot gradedqualityBmaintenanceMCP 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
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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