DataGSM(광주소프트웨어마이스터고등학교 OpenAPI + OAuth 서비스) MCP 서버
Claude가 DataGSM의 학생, 동아리, 급식, 학사일정 데이터를 직접 조회하고, 기술 문서를 검색하며, OAuth 흐름을 안내받을 수 있습니다.
도구 | 인증 | 설명 |
| 불필요 | 키워드로 DataGSM 공식 문서 검색 |
| 불필요 | 특정 URL의 문서 페이지 조회 |
| 불필요 | 전체 문서 목록 조회 |
| 불필요 | API Key Scope 목록과 권한 설명 |
| 불필요 | OAuth PKCE 흐름 설명 및 Authorization URL 생성 |
| API Key | 학생 목록 조회 (학년/반/전공 등 필터) |
| API Key | 동아리 목록 조회 |
| API Key | 프로젝트 목록 조회 |
| API Key | NEIS 급식 정보 조회 |
| API Key | NEIS 학사일정 조회 |
| API Key | NEIS 시간표 조회 |
Related MCP server: Canvas MCP Server
~/Library/Application Support/Claude/claude_desktop_config.json 에 추가:
{
"mcpServers": {
"datagsm": {
"command": "npx",
"args": ["-y", "datagsm-mcp"],
"env": {
"DATAGSM_API_KEY": "your-api-key"
}
}
}
}claude mcp add datagsm -e DATAGSM_API_KEY=your-api-key -- npx -y datagsm-mcp변수 | 필수 | 기본값 | 설명 |
| 데이터 조회 시 | — | OpenAPI 인증 키 |
| Bearer 사용 시 | — | OAuth Access Token |
| 선택 |
| OpenAPI 서버 URL |
| 선택 |
| OAuth 서버 URL |
| 선택 |
| 문서 목록 URL |
git clone https://github.com/your-org/datagsm-mcp
cd datagsm-mcp
npm install
npm run build
# MCP Inspector로 테스트
npx @modelcontextprotocol/inspector node build/index.jsGit 태그 푸시 시 자동으로 npm에 배포됩니다:
# package.json version 업데이트 후
git tag v1.0.0
git push origin v1.0.0GitHub 저장소 Settings > Secrets에 NPM_TOKEN을 등록해야 합니다.
DataGSM API Key의 모든 권한 Scope와 설명을 반환합니다. API Key 발급 시 어떤 Scope를 요청해야 하는지 안내할 때 사용하세요.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | 표시할 Scope 범위: all(전체), user(USER 역할), admin(ADMIN 역할) | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint; the description confirms a read operation but adds no additional behavioral details such as rate limits or permission requirements.
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 two sentences long, front-loaded with the primary action and purpose, containing no unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one optional parameter and no output schema, the description adequately explains the return value and usage context, though it omits details about output structure or pagination.
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 description coverage is 100%, and the parameter description in the schema already explains the filter. The tool description does not add further semantic value 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 'returns' and the resource 'all permission scopes and descriptions of DataGSM API Key', distinguishing it from sibling tools that deal with other entities like clubs or students.
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 explicitly advises when to use this tool: 'when guiding which scopes to request when issuing API Key', providing clear context though lacking explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DataGSM OAuth 2.0 Authorization Code + PKCE 흐름을 단계별로 설명합니다. clientId를 제공하면 실제 Authorization URL을 생성합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| clientId | No | 등록된 OAuth 클라이언트 ID (제공 시 authorize URL 생성) | |
| redirectUri | No | 리다이렉트 URI | |
| scopes | No | 요청할 scope 목록 (예: ["self:read"]) | |
| state | No | CSRF 방지용 state 값 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true, and the description aligns by describing read-only operations (explanation and URL generation). The description adds detail about conditional URL generation based on clientId, which goes beyond annotations without contradiction.
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 in Korean with no fluff. The first sentence states the main purpose (explain flow step by step), and the second adds conditional behavior. Every sentence is necessary and 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 tool is explanatory and has no output schema, the description sufficiently covers its purpose and conditional behavior. It could be improved by briefly mentioning the response format (e.g., step-by-step text and the generated URL), but the current text is adequate for an agent to understand what to expect.
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 100% parameter description coverage, so the description adds limited per-parameter value. The tool description mentions that clientId triggers URL generation, which is already noted in the schema description for that parameter. The overall flow context is helpful but not critical beyond 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 explains the OAuth 2.0 Authorization Code + PKCE flow step by step and can generate an Authorization URL if a clientId is provided. The verb 'explain' and 'generate' are specific, and the resource ('OAuth flow') is well-defined, differentiating it from sibling data retrieval 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 implies usage for explaining the OAuth flow and generating URLs, but does not explicitly state when not to use it or compare with alternatives. However, given the sibling tools are all data-oriented, the purpose is distinct enough to guide appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DataGSM에서 동아리 목록을 조회합니다. 동아리 종류, 운영 상태 등으로 필터링할 수 있습니다. API Key(DATAGSM_API_KEY)가 환경변수에 설정되어 있어야 합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| clubId | No | 특정 동아리 ID | |
| clubName | No | 동아리 이름 (부분 일치) | |
| clubType | No | 동아리 종류 (MAJOR_CLUB: 학과 동아리, AUTONOMOUS_CLUB: 자율 동아리) | |
| clubStatus | No | 운영 상태 (ACTIVE: 활성, ABOLISHED: 폐부) | |
| foundedYear | No | 창설 학년도 | |
| includeLeaderInParticipants | No | 부장을 부원 목록에 포함할지 여부 | |
| page | No | 페이지 번호 (0부터 시작) | |
| size | No | 페이지 크기 (최대 100) | |
| sortBy | No | 정렬 기준 | |
| sortDirection | No | 정렬 방향 | ASC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds the API key requirement, but does not disclose other behavioral traits such as pagination behavior, rate limits, or default parameter values. No contradiction.
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 extraneous information. However, it is quite minimal and could benefit from a more structured format. Still, it is appropriately sized for a simple list endpoint.
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 10 parameters including pagination, sorting, and multiple filters, the description is too brief. It does not explain pagination, default values, or response format. No output schema exists, so the description should compensate, but it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds a vague 'etc.' but no additional meaning beyond the schema. Parameter descriptions in the schema already cover the filter fields.
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 retrieves a list of clubs from DataGSM and supports filtering by type and status. Verb and resource are specific, and the tool is distinct from siblings like get_projects or get_students.
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 mentions the prerequisite of an API key environment variable, but lacks explicit guidance on when to use this tool vs alternatives or when not to use it. No comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DataGSM 문서 사이트의 특정 URL 페이지 내용을 가져옵니다. search_docs로 찾은 URL을 직접 조회하거나, 알고 있는 문서 경로를 바로 읽을 때 사용하세요.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | 조회할 문서 URL (예: "https://docs.datagsm.kr/oauth/pkce") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds that it fetches page content, but does not disclose potential issues like invalid URLs or rate limits. With annotations handling the main behavioral traits, a score of 3 is appropriate.
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, no wasted words. The first sentence states the primary function, the second clarifies usage scenarios. Front-loaded 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?
Given the simple, read-only nature of the tool (1 parameter, annotations cover safety), the description fully specifies purpose, usage, and example. No gaps remain for an AI agent to interpret.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter (url). The description adds an example URL format and ties usage to search_docs, providing context beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it fetches content of a specific URL from the DataGSM document site, using verbs '가져옵니다' (fetches) and '조회' (query). It distinguishes from siblings like search_docs (search) and list_docs (list) by specifying direct URL access.
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 instructs to use this tool to directly query URLs found via search_docs or to read known document paths, providing clear usage context. However, it does not explicitly state when not to use it or mention alternatives beyond search_docs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
NEIS 연동 급식 정보를 조회합니다. 특정 날짜 또는 기간의 급식 메뉴와 알레르기 정보를 확인할 수 있습니다. API Key(DATAGSM_API_KEY)가 환경변수에 설정되어 있어야 합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | 단일 날짜 (YYYY-MM-DD). date 또는 fromDate+toDate 중 하나만 사용 | |
| fromDate | No | 조회 시작 날짜 (YYYY-MM-DD) | |
| toDate | No | 조회 종료 날짜 (YYYY-MM-DD). 최대 365일 범위 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and the description confirms it is a read operation. It adds context about the external NEIS integration and the type of information returned (menus, allergies), which goes beyond 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 concise sentences cover purpose, prerequisites, and capabilities 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 high schema coverage, read-only annotation, and clear purpose, the description is complete. It implies return values (menu and allergy info) without needing an 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 coverage is 100% with descriptions for each parameter. The description's mention of date options aligns with schema but adds no new semantic value beyond what the schema already provides.
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 retrieves NEIS-linked meal information, including menu and allergy data for a specific date or period. This is distinct from sibling tools like get_schedules or get_timetables.
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 specifies that an API key must be set as an environment variable and explains the two modes of date input (single date vs. range). However, it does not explicitly state when not to use this tool, though context suggests it's the only meal tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DataGSM에서 프로젝트 목록을 조회합니다. 동아리별, 상태별로 필터링할 수 있습니다. API Key(DATAGSM_API_KEY)가 환경변수에 설정되어 있어야 합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | No | 특정 프로젝트 ID | |
| projectName | No | 프로젝트 이름 (부분 일치) | |
| clubId | No | 연관 동아리 ID로 필터링 | |
| status | No | 프로젝트 상태 (ACTIVE: 진행 중, ENDED: 종료) | |
| page | No | 페이지 번호 (0부터 시작) | |
| size | No | 페이지 크기 (최대 100) | |
| sortBy | No | 정렬 기준 | |
| sortDirection | No | 정렬 방향 | ASC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and description confirms it retrieves data. Adds value by specifying authentication requirement (API key in env), which is not in 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 concise sentences with front-loaded purpose and immediate important context (filtering, auth). 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?
No output schema, and description omits pagination, sorting, and response structure details. For a list tool with 8 parameters, this is insufficient for 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?
Input schema has 100% description coverage, so the description adds minimal additional meaning beyond summarizing filtering options. Baseline 3 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?
Description clearly states it retrieves a project list and supports filtering by club and status. It distinguishes from sibling tools (e.g., get_clubs, get_students) by specifying the resource as projects.
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?
Mentions filter options and prerequisite API key, but does not provide guidance on when to use this tool versus alternatives (e.g., search_docs). No explicit when-not or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
NEIS 연동 학사일정을 조회합니다. 특정 날짜 또는 기간의 행사 및 학사 일정을 확인할 수 있습니다. API Key(DATAGSM_API_KEY)가 환경변수에 설정되어 있어야 합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | 단일 날짜 (YYYY-MM-DD). date 또는 fromDate+toDate 중 하나만 사용 | |
| fromDate | No | 조회 시작 날짜 (YYYY-MM-DD) | |
| toDate | No | 조회 종료 날짜 (YYYY-MM-DD). 최대 365일 범위 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description aligns by stating retrieval. The description adds the requirement for the API key, but does not disclose other behavioral traits such as rate limits or data volume constraints beyond what the schema notes.
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. The first sentence immediately states the core purpose, and the second adds a crucial prerequisite. No redundant or vague language.
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 good annotations, the description omits important details: it does not explain the two usage modes (single date vs. date range) or describe the output format. Since there is no output schema, the agent lacks information about what data will be returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description does not add new meaning about parameters beyond repeating the date/period concept. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves academic schedules integrated with NEIS, using specific verbs ('조회합니다') and specifying the resource ('학사일정'). It distinguishes from siblings like get_timetables by focusing on school events rather than class 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?
The description implies usage for checking events on specific dates or periods, and mentions the API key prerequisite. However, it provides no explicit guidance on when to use this tool versus alternatives, nor 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.
DataGSM에서 학생 목록을 조회합니다. 학년, 반, 전공 등 다양한 조건으로 필터링할 수 있습니다. API Key(DATAGSM_API_KEY)가 환경변수에 설정되어 있어야 합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| studentId | No | 특정 학생 ID | |
| name | No | 학생 이름 (부분 일치) | |
| No | 학생 이메일 | ||
| grade | No | 학년 (1~3) | |
| classNum | No | 반 (1~4) | |
| number | No | 번호 (1~18) | |
| sex | No | 성별 | |
| role | No | 학생 역할 | |
| major | No | 전공 (SW개발과, 스마트IOT과, AI과) | |
| dormitoryRoom | No | 기숙사 호실 번호 | |
| githubId | No | GitHub ID | |
| includeGraduates | No | 졸업생 포함 여부 | |
| includeWithdrawn | No | 자퇴생 포함 여부 | |
| onlyEnrolled | No | 재학생만 조회 | |
| page | No | 페이지 번호 (0부터 시작) | |
| size | No | 페이지 크기 (최대 300) | |
| sortBy | No | 정렬 기준 | |
| sortDirection | No | 정렬 방향 (ASC: 오름차순, DESC: 내림차순) | ASC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool is known to be read-only. The description adds the API key requirement but no other behavioral context like pagination or rate limits. This is adequate given the annotation coverage.
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 two sentences, front-loaded with the core purpose, and contains no unnecessary information. 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?
For a tool with 18 parameters and no output schema, the description does not explain return structure or common use cases. However, the schema is very detailed, and annotations cover read-only nature, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no additional parameter meaning beyond what the schema provides; it only mentions the API key env var, which is 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 retrieves a student list from DataGSM and mentions filtering by grade, class, major, etc. It distinguishes itself from sibling tools, which are all other entity types (clubs, projects, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is the tool for retrieving student lists, with filtering options. It does not explicitly state when to use alternatives, but since no other student retrieval tool exists, the usage is clear. The API key prerequisite is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
NEIS 연동 시간표를 조회합니다. 학년과 반을 지정하고 날짜 또는 기간을 입력해야 합니다. API Key(DATAGSM_API_KEY)가 환경변수에 설정되어 있어야 합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| grade | Yes | 학년 (1~3, 필수) | |
| classNum | Yes | 반 (1~4, 필수) | |
| date | No | 단일 날짜 (YYYY-MM-DD). date 또는 fromDate+toDate 중 하나만 사용 | |
| fromDate | No | 조회 시작 날짜 (YYYY-MM-DD) | |
| toDate | No | 조회 종료 날짜 (YYYY-MM-DD). 최대 365일 범위 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the information that an API key (DATAGSM_API_KEY) must be set in environment variables and implies that at least one date parameter is required, which is not fully enforced by the schema. The annotations already declare readOnlyHint=true, so the read-only behavior is covered. No additional behavioral traits like rate limits or pagination are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, each providing essential information: what the tool does, required inputs, and a prerequisite (API key). It is front-loaded and contains no redundant or 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?
Given the absence of an output schema, the description does not explain the return format or structure. It covers input requirements adequately but misses information about error conditions, pagination, or data limits. The complexity is moderate, so a bit more context would be beneficial.
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 100% schema coverage, the baseline is 3. The description adds value by clarifying that exactly one of 'date' or 'fromDate+toDate' must be used (beyond the schema's optional fields), and it reiterates the need for grade and class. This extra context improves parameter understanding.
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 queries 'NEIS 연동 시간표' (timetable) and specifies the required inputs: grade, class, and date/period. It is a specific verb+resource combination, but it does not explicitly distinguish from the sibling tool 'get_schedules', leaving some ambiguity.
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 that grade, class, and a date/period are required, and that an API key is needed. However, it does not provide guidance on when to use this tool over siblings (e.g., get_schedules), nor does it mention any exclusions or prerequisites beyond the API key.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DataGSM 공식 문서의 전체 페이지 목록과 URL을 반환합니다. 어떤 문서가 있는지 파악하거나 search_docs 전에 목록을 확인할 때 사용하세요.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behaviors. Description adds that it returns pages and URLs, which is useful but could mention more about output format. 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?
Two front-loaded sentences that are perfectly concise, each providing essential information without waste.
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 tool with no parameters and no output schema, the description covers purpose and usage, but lacks explicit output structure (e.g., array of objects with name and url). 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?
No parameters exist, so schema coverage is 100%. Description adds value by stating the output includes pages and URLs, but no parameter details needed. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns the full list of official DataGSM document pages and URLs, and distinguishes from sibling search_docs by advising use before searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use when wanting to understand available documents or to check the list before search_docs, providing clear context and exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DataGSM 공식 문서에서 키워드와 관련된 페이지를 찾아 내용을 반환합니다. API 사용법, OAuth 흐름, SDK 안내, Scope 정보 등을 검색할 때 사용하세요.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | 검색할 키워드 (예: "OAuth PKCE", "학생 필터링", "급식 API", "SDK 사용법") | |
| maxResults | No | 반환할 최대 페이지 수 (기본값: 3) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's statement of returning page content adds some behavioral context but no details about rate limits, authentication, or how results are structured. The description does not contradict 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 sentences: first clearly states purpose, second lists use cases. No fluff, every sentence contributes value. Front-loaded 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?
Given simple parameters and absence of output schema, the description adequately covers purpose and typical usage. It lacks details on result format or ordering, but this is minor for a straightforward search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters described. The description adds example values for the query parameter (e.g., 'OAuth PKCE') but does not explain parameter behavior beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool searches DataGSM official docs for keyword-related pages and returns content. It lists specific use cases (API usage, OAuth flow, SDK guide, Scope info), distinguishing it from sibling tools like get_doc (retrieves single doc) and list_docs (lists all docs).
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 provides explicit use cases (searching for API usage, OAuth, SDK, Scope info), guiding when to use. It does not explicitly mention when not to use or list alternatives, but the sibling tools are clearly different, making the context sufficient.
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.
v1.0.2describe_scopesexplain_oauth_flowget_clubsget_docget_mealsget_projectsget_schedulesget_studentsget_timetableslist_docssearch_docsScored across 11 tools
Each tool has a clearly distinct purpose: scopes, OAuth flow, clubs, meals, projects, schedules, students, timetables, and documentation (list, search, get). No overlapping functionality.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_clubs, list_docs, describe_scopes). No mixing of conventions.
11 tools is appropriate for the server's purpose—covering authentication info, data retrieval (clubs, projects, students, meals, schedules, timetables), and documentation. Well-scoped.
The tool surface covers the main informational needs (read operations for key entities and documentation). Missing create/update/delete operations, but given the server's likely read-only purpose, only minor gaps remain (e.g., no user info tool).
Provides tools for searching Google Workspace documentation and much more.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
Connect Claude to your Platform7n workspaces — chat, links, and tasks. One-click OAuth.
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
