StrangeBee/TheHive Project의 Cortex를 위한 MCP(Model Context Protocol) 서버입니다. Cortex는 분석기를 사용하여 관찰 가능 항목(IP, URL, 해시, 도메인, 이메일, 파일)의 분석을 자동화하고, 대응기를 통해 대응 작업을 실행합니다. 이 MCP 서버는 Cortex의 전체 분석 및 관리 파이프라인을 LLM에 노출합니다.
31개의 MCP 도구: 전체 Cortex API 표면을 포괄
4개의 MCP 리소스: Cortex 상태 탐색용
4개의 MCP 프롬프트: 가이드 워크플로우 제공(설정, 조사, 분류)
전체 분석기/대응기 수명 주기: 정의 탐색, 활성화, 구성, 비활성화
관찰 가능 데이터 유형 자동 감지(IP, 도메인, 해시, URL, 이메일)
분류 체계 집계를 포함한 모든 적용 가능한 분석기에 대한 대량 분석
드라이런(dry-run) 지원을 포함한 작업 정리
사용자 API 키 관리(생성, 갱신, 검색)
상태 관리를 포함한 조직 CRUD
이중 API 키 지원: 조직 수준 작업 + 슈퍼 관리자 관리
Related MCP server: misp-mcp
Node.js 20 이상
실행 중인 Cortex 인스턴스(v3.x 권장)
적절한 권한이 있는 Cortex API 키
git clone https://github.com/solomonneas/cortex-mcp.git
cd cortex-mcp
npm install
npm run build변수 | 필수 | 기본값 | 설명 |
| 예 | - | Cortex 기본 URL (예: |
| 예 | - | 일반 작업용 API 키 (조직 관리자 수준) |
| 아니요 | - | 조직/사용자/정의 관리용 슈퍼 관리자 API 키 |
| 아니요 |
| SSL 확인을 건너뛰려면 |
| 아니요 |
| 요청 시간 제한(초) |
~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)에 추가하세요:
{
"mcpServers": {
"cortex": {
"command": "cortex-mcp",
"env": {
"CORTEX_URL": "http://cortex.example.com:9001",
"CORTEX_API_KEY": "your-org-admin-key",
"CORTEX_SUPERADMIN_KEY": "your-superadmin-key"
}
}
}
}claude mcp add cortex \
--env CORTEX_URL=http://cortex.example.com:9001 \
--env CORTEX_API_KEY=your-org-admin-key \
--env CORTEX_SUPERADMIN_KEY=your-superadmin-key \
-- cortex-mcp현재 프로젝트뿐만 아니라 모든 디렉토리에서 사용할 수 있도록 --scope user를 추가하세요.
npm 설치 바이너리 대신 소스 체크아웃에서 실행하는 경우, command/args를 빌드된 dist/index.js로 지정하세요:
openclaw mcp set cortex '{
"command": "node",
"args": ["/absolute/path/to/cortex-mcp/dist/index.js"],
"env": {
"CORTEX_URL": "http://cortex.example.com:9001",
"CORTEX_API_KEY": "your-org-admin-key",
"CORTEX_SUPERADMIN_KEY": "your-superadmin-key"
}
}'또는 전역 npm 설치를 사용하는 경우:
openclaw mcp set cortex '{
"command": "cortex-mcp",
"env": {
"CORTEX_URL": "http://cortex.example.com:9001",
"CORTEX_API_KEY": "your-org-admin-key",
"CORTEX_SUPERADMIN_KEY": "your-superadmin-key"
}
}'그런 다음 OpenClaw 게이트웨이를 다시 시작하여 새 서버가 선택되도록 하세요:
systemctl --user restart openclaw-gateway
openclaw mcp list # confirm "cortex" is registeredHermes Agent는 mcp_servers 키 아래의 ~/.hermes/config.yaml에서 MCP 구성을 읽습니다. 항목을 추가하세요:
mcp_servers:
cortex:
command: "cortex-mcp"
env:
CORTEX_URL: "http://cortex.example.com:9001"
CORTEX_API_KEY: "your-org-admin-key"
CORTEX_SUPERADMIN_KEY: "your-superadmin-key"또는 전역 npm 설치 대신 소스 체크아웃에서 실행하는 경우:
mcp_servers:
cortex:
command: "node"
args: ["/absolute/path/to/cortex-mcp/dist/index.js"]
env:
CORTEX_URL: "http://cortex.example.com:9001"
CORTEX_API_KEY: "your-org-admin-key"
CORTEX_SUPERADMIN_KEY: "your-superadmin-key"그런 다음 Hermes 세션 내에서 MCP를 다시 로드하세요:
/reload-mcpCodex CLI는 codex mcp add를 통해 MCP 서버를 등록합니다:
codex mcp add cortex \
--env CORTEX_URL=http://cortex.example.com:9001 \
--env CORTEX_API_KEY=your-org-admin-key \
--env CORTEX_SUPERADMIN_KEY=your-superadmin-key \
-- cortex-mcp또는 소스 체크아웃에서 실행하는 경우:
codex mcp add cortex \
--env CORTEX_URL=http://cortex.example.com:9001 \
--env CORTEX_API_KEY=your-org-admin-key \
--env CORTEX_SUPERADMIN_KEY=your-superadmin-key \
-- node /absolute/path/to/cortex-mcp/dist/index.jsCodex는 [mcp_servers.cortex] 아래의 ~/.codex/config.toml에 항목을 작성합니다. 다음으로 확인하세요:
codex mcp listexport CORTEX_URL=http://cortex.example.com:9001
export CORTEX_API_KEY=your-org-admin-key
npm start도구 | 설명 |
| Cortex 인스턴스 상태, 버전 및 구성 가져오기 |
도구 | 설명 |
| 활성화된 모든 분석기 나열(데이터 유형별 필터링 가능) |
| ID별 특정 분석기에 대한 세부 정보 가져오기 |
| 분석을 위해 관찰 가능 항목을 특정 분석기에 제출 |
| ID 대신 이름으로 분석기 실행(편의 래퍼) |
| 분석을 위해 파일(경로 또는 base64)을 분석기에 제출 |
도구 | 설명 |
| 필터링(데이터 유형, 무료/구성 불필요, 검색)을 통해 260개 이상의 사용 가능한 분석기 정의 탐색 |
| 구성과 함께 현재 조직에서 분석기 정의 활성화 |
| 활성화된 분석기 비활성화(제거) |
도구 | 설명 |
| 분석 작업의 상태 및 세부 정보 가져오기 |
| 완료된 분석 작업의 전체 보고서 가져오기 |
| 작업이 완료될 때까지 기다린 후 보고서 반환 |
| 선택적 필터를 사용하여 최근 분석 작업 나열 |
| 완료된 작업에서 아티팩트(추출된 IOC) 가져오기 |
| 특정 작업 삭제 |
| 상태 또는 기간별로 작업 대량 삭제(드라이런 지원) |
도구 | 설명 |
| 활성화된 모든 대응기 나열(데이터 유형별 필터링 가능) |
| TheHive 엔티티에 대해 대응기 작업 실행 |
도구 | 설명 |
| 필터링을 통해 137개 이상의 사용 가능한 대응기 정의 탐색 |
| 구성과 함께 대응기 정의 활성화 |
| 활성화된 대응기 비활성화(제거) |
도구 | 설명 |
| 자동 감지된 데이터 유형 및 집계된 분류 체계 결과를 사용하여 적용 가능한 모든 분석기 실행 |
도구 | 설명 |
| 모든 조직 나열 |
| 조직 세부 정보 가져오기 |
| 새 조직 생성 |
| 조직 설명 또는 상태 업데이트 |
도구 | 설명 |
| 조직 전체의 모든 사용자 나열 |
| 사용자 세부 정보 가져오기 |
| 조직 내 새 사용자 생성 |
| 사용자를 위한 새 API 키 생성(이전 키 무효화) |
| 사용자의 현재 API 키 검색 |
URI | 설명 |
| 기능이 포함된 활성화된 분석기 |
| 구성 요구 사항이 포함된 260개 이상의 모든 사용 가능한 분석기 정의 |
| 구성 요구 사항이 포함된 137개 이상의 모든 사용 가능한 대응기 정의 |
| 최근 50개의 분석 작업 |
프롬프트 | 설명 |
| Cortex를 통해 관찰 가능 항목을 분석하기 위한 가이드 워크플로우 |
| 의심스러운 IOC에 대한 심층 조사 워크플로우 |
| 새로운 Cortex 인스턴스를 위한 가이드 설정 마법사(무료 분석기 활성화, API 키 구성) |
| 다중 관찰 가능 항목 분석 및 위험 평가를 포함한 구조화된 경고 분류 워크플로우 |
1. Use cortex_list_analyzer_definitions with freeOnly=true to find analyzers
that need no API keys.
2. Use cortex_enable_analyzer to enable "Abuse_Finder_3_0" with empty config.
3. Use cortex_analyze_observable with data "8.8.8.8" to analyze the IP.Use cortex_analyze_observable with data "185.220.101.42"
(no dataType needed - auto-detects as IP)Use cortex_cleanup_jobs with status "Failure", dryRun true to preview,
then dryRun false to delete.Use cortex_run_analyzer_file with analyzerId "Yara_3_0",
filePath "/tmp/suspicious.exe" to scan with YARA rules.Use cortex_renew_user_key with userId "analyst1" to rotate their API key.Use the triage-alert prompt with alertDescription "Suspicious outbound traffic
detected" and observables "185.220.101.42, evil.example.com, 44d88612fea8a8f36de82e1278abb02f"유형 | 예시 | 자동 감지 |
|
| ✅ |
|
| ✅ |
|
| ✅ |
| MD5, SHA1, SHA256, SHA512 | ✅ |
|
| ✅ |
|
| 도메인으로 |
|
| 수동 |
|
| 수동 |
| 바이너리 파일 업로드 | 수동 |
| CVE, 사용자 지정 유형 | 수동 |
npm test # Unit tests (36 tests)
npm run test:watch # Watch mode
npm run lint # Type check
# Integration tests (requires live Cortex instance)
CORTEX_URL=http://cortex:9001 \
CORTEX_API_KEY=your-key \
CORTEX_SUPERADMIN_KEY=your-superadmin-key \
npx vitest run tests/integration.test.tscortex-mcp/
src/
index.ts # MCP server entry point
config.ts # Environment config + validation
client.ts # Cortex REST API client (full surface)
types.ts # Cortex API type definitions
resources.ts # MCP resources (4)
prompts.ts # MCP prompts (2)
tools/
analyzers.ts # Analyzer tools (list, get, run, run-by-name)
analyzer-definitions.ts # Definition browsing, enable, disable
jobs.ts # Job management + cleanup
responders.ts # Responder tools (list, run)
responder-definitions.ts # Definition browsing, enable, disable
bulk.ts # Bulk analysis with auto-detect
status.ts # Health/version check
organizations.ts # Org CRUD (superadmin)
users.ts # User CRUD + key management (superadmin)
tests/
client.test.ts # API client unit tests
tools.test.ts # Tool handler unit tests
integration.test.ts # Live instance integration tests (21 tests)
scripts/
proxmox_install.sh # Proxmox LXC deployment scriptbash -c "$(wget -qLO - https://raw.githubusercontent.com/solomonneas/cortex-mcp/main/scripts/proxmox_install.sh)"MIT
Run applicable analyzers against an observable and collect aggregated results with taxonomy summary. Can auto-detect data type. By default only an explicit allowlist of analyzers runs; set fanOut=true to submit to every applicable analyzer (capped by CORTEX_MAX_FANOUT). Fanning out submits the observable to many third-party services (SSRF-by-proxy / IOC disclosure / quota burn), so it is opt-in.
| Name | Required | Description | Default |
|---|---|---|---|
| pap | No | Permissible Actions Protocol level (0-3). Default: 2 | |
| tlp | No | Traffic Light Protocol level (0=WHITE, 1=GREEN, 2=AMBER, 3=RED). Default: 2/AMBER | |
| data | Yes | The observable value (IP, domain, hash, URL, email, etc.) | |
| fanOut | No | If true, submit the observable to ALL applicable analyzers (capped by maxAnalyzers / CORTEX_MAX_FANOUT). Default false: you must pass an `analyzers` allowlist. | |
| timeout | No | Timeout in seconds per analyzer (default: 300) | |
| dataType | No | The observable data type. If omitted, will be auto-detected from the value. | |
| analyzers | No | Explicit allowlist of analyzer names (substring match, case-insensitive) to run. Required unless fanOut=true. Only matching analyzers that also support the data type are submitted. | |
| maxAnalyzers | No | Hard cap on how many analyzers to run this call. Defaults to and is clamped by the server's CORTEX_MAX_FANOUT (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses auto-detection, the allowlist vs fan-out behavior, risks of fan-out (SSRF, IOC disclosure, quota burn), and the cap via CORTEX_MAX_FANOUT. It does not describe the return value structure or error handling.
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 and packs essential information without fluff. The first sentence is dense but covers the core purpose and key features.
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 8 parameters and no output schema, the description does not detail the return value format (only mentions 'aggregated results with taxonomy summary'). It also omits behavior for timeouts or error handling. However, the schema and annotations cover many aspects, making it adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context about fanOut risks and auto-detection, but the schema already explains the parameters well. The added value is marginal.
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 'Run analyzers' and the resource 'observable'. It mentions 'aggregated results with taxonomy summary', which distinguishes it from sibling tools like cortex_run_analyzer that run a single analyzer.
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 contrasts the two modes: 'only an explicit allowlist' vs 'fanOut=true', and explains that fanning out is opt-in due to third-party risks. It does not, however, explicitly recommend when to use this tool over sibling tools like cortex_run_analyzer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple jobs by status or age. Useful for cleaning up failed or old jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum jobs to process (default: 100) | |
| dryRun | No | If true (default), only count matching jobs without deleting them | |
| status | No | Delete jobs with this status | |
| olderThanDays | No | Delete jobs older than this many days |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states 'Delete' indicating mutability, but does not elaborate on irreversibility, authorization needs, or rate limits. The schema covers dryRun behavior, so the description adds minimal behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the core action, the second provides a use case. No filler words, efficient 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 4 parameters with 100% schema coverage and no output schema, the description is adequate. It explains the tool's purpose and filtering. However, it does not clarify whether combining 'status' and 'olderThanDays' uses AND or OR logic, but the schema hints at separate usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description mentions filtering 'by status or age,' aligning with the 'status' and 'olderThanDays' parameters, but does not add significant meaning beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete multiple jobs by status or age' and gives a use case 'cleaning up failed or old jobs.' It distinguishes from siblings like cortex_delete_job (single job) and cortex_list_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case ('cleaning up failed or old jobs') but does not explicitly mention when not to use or compare to alternatives like cortex_delete_job for single deletions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new organization in Cortex (requires superadmin API key)
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Organization name (used as ID, no spaces recommended) | |
| description | Yes | Organization description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the auth requirement but does not explain side effects, success/failure outcomes, or return value. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key purpose and constraint. Every word is necessary and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with no output schema, the description covers the core action and a requirement but does not mention what the tool returns or any post-conditions. It is 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 coverage is 100%, and the description adds value by clarifying that the name is used as an ID with no spaces recommended, which goes beyond the schema's description. The description parameter adds no extra info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Create), resource (new organization), and context (in Cortex), with a specific prerequisite (requires superadmin API key). This effectively distinguishes it from siblings like cortex_create_user.
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 includes a key usage condition (superadmin API key) but does not explicitly state when to use this tool versus alternatives like cortex_update_organization. However, the purpose is clear enough for basic selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new user in an organization (requires superadmin API key)
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | User display name | |
| login | Yes | User login (used as ID) | |
| roles | Yes | User roles: "read", "analyze", "orgadmin", or "superadmin" | |
| password | No | Optional initial password | |
| organization | Yes | Organization to assign the user to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states 'Create' (mutation) and the auth requirement, but it does not mention possible error states (e.g., duplicate login), idempotency, rate limits, or the response format. This leaves significant undocumented behavioral aspects.
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 contains all essential information: the action, resource, and a key constraint. There is no unnecessary 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?
The tool has no output schema and 5 parameters. While the description and schema cover the inputs, the lack of any mention of return values or error behavior (e.g., what happens on success or failure) leaves the agent uncertain about the outcome. However, for a standard creation tool, the description is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 5 parameters with descriptions (100% coverage). The description does not add semantic value beyond what the schema provides. Per guidelines, baseline 3 is appropriate when schema coverage is high.
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 'Create a new user in an organization', specifying the verb 'Create' and the resource 'user in an organization'. This distinguishes it from sibling tools like cortex_list_users (list) and cortex_get_user (retrieve). The additional context 'requires superadmin API key' further clarifies the intended scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes the requirement for a superadmin API key, which is a critical usage prerequisite. While it does not provide explicit exclusions or alternative tools, the context of user creation is clear, and the sibling names make distinctions straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a specific analysis job by ID. DESTRUCTIVE: requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | The job ID to delete | |
| confirm | No | Must be set to true to actually delete the job. Defaults to false as a safety guard. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry the burden. It discloses destructive nature and the safety guard (confirm flag), but lacks details on idempotency, error behavior, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The key information (verb, resource, destructiveness, requirement) is 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?
For a simple delete operation with no output schema, the description covers the essential behavioral constraints. Missing return value details, but acceptable given the tool's simplicity.
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 the description adds marginal value. It notes that confirm is a safety guard, which reinforces the schema's default, but does not add new semantics for jobId.
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 'Delete' and the resource 'a specific analysis job by ID', distinguishing it from sibling tools like cortex_get_job (read) and cortex_cleanup_jobs (bulk).
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 warns about destructiveness and requires confirm=true, providing clear context for use. However, it does not explicitly state when not to use or compare to alternatives, though the destructiveness hint implies caution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disable (remove) an enabled analyzer from the current organization. DESTRUCTIVE: requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be set to true to actually disable/remove the analyzer. Defaults to false as a safety guard. | |
| analyzerId | Yes | The enabled analyzer's ID (the internal ID from cortex_list_analyzers, not the definition ID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It declares the tool as 'DESTRUCTIVE' and notes the confirm flag requirement. This provides essential behavioral insight. Additional details like rate limits or auth scope are not provided, but the core destructiveness is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. Every word adds value: the action, scope, destructiveness warning, and confirmation requirement. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: what it does, destructiveness, and parameter source (ID from list_analyzers). With no output schema, it doesn't explain return values, but for a disable operation, this is likely sufficient. Could explicitly mention it as inverse of cortex_enable_analyzer.
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. The description reinforces the confirm requirement but adds no extra meaning beyond the schema, which already explains the default and ID source. The description's mention of 'requires confirm=true' echoes schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Disable (remove) an enabled analyzer' and specifies the scope 'from the current organization'. It distinguishes from siblings like cortex_enable_analyzer and cortex_list_analyzers, making the tool's purpose obvious.
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 highlights the destructive nature and the need for confirm=true. While it doesn't explicitly list alternatives, the sibling tool names (e.g., cortex_enable_analyzer) provide context. The safety guard is well emphasized.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disable (remove) an enabled responder from the current organization
| Name | Required | Description | Default |
|---|---|---|---|
| responderId | Yes | The enabled responder's ID (the internal ID from cortex_list_responders, not the definition ID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states the action without disclosing side effects, permissions needed, or error conditions. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and directly states the tool's purpose without any redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description is adequate but lacks broader context. It does not mention usage guidelines, consequences of the action, or relationship to other tools, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, responderId, is fully described in the schema (100% coverage). The description adds valuable context by specifying it is the internal ID from cortex_list_responders and not the definition ID, which aids correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Disable (remove) an enabled responder' and specifies the scope 'from the current organization'. It uses a specific verb and resource, naturally distinguishing from sibling tools like cortex_enable_responder.
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 cortex_enable_responder or cortex_list_responders. There is no mention of prerequisites or typical usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable an analyzer definition in the current organization. Provide configuration values for any required fields.
| Name | Required | Description | Default |
|---|---|---|---|
| rate | No | Rate limit: max jobs per rate unit (default: 100) | |
| jobCache | No | Cache duration in minutes for identical jobs (default: 10) | |
| rateUnit | No | Rate limit unit (default: Day) | Day |
| definitionId | Yes | The analyzer definition ID (e.g., 'Abuse_Finder_3_0', 'VirusTotal_GetReport_3_1') | |
| configuration | No | Configuration key-value pairs (API keys, URLs, etc.). Check cortex_list_analyzer_definitions for required fields. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It fails to mention idempotency, overwriting behavior, or effects of enabling an already enabled analyzer. The parameters rate, rateUnit, and jobCache are not explained in the description, leaving their purpose unclear.
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 concise at two sentences, front-loading the main action. Every sentence is essential and contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, no output schema, and no annotations. The description omits details on optional parameters and behavioral guarantees, leaving an agent uncertain about usage and side effects.
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 covers all parameters with descriptions, so baseline is 3. The description adds context about required configuration fields but does not elaborate on rate, rateUnit, or jobCache beyond the schema. Thus, little additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Enable', the resource 'analyzer definition', and the scope 'in the current organization'. It effectively distinguishes from sibling tools like cortex_disable_analyzer or cortex_run_analyzer.
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 advises to provide configuration values for required fields and references cortex_list_analyzer_definitions for needed fields, giving practical guidance. However, it does not explicitly state when not to use this tool or mention alternatives like disabling or listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable a responder definition in the current organization. Provide configuration values for any required fields.
| Name | Required | Description | Default |
|---|---|---|---|
| rate | No | Rate limit: max executions per rate unit (default: 100) | |
| rateUnit | No | Rate limit unit (default: Day) | Day |
| definitionId | Yes | The responder definition ID (e.g., 'Mailer_1_0') | |
| configuration | No | Configuration key-value pairs. Check cortex_list_responder_definitions for required fields. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It indicates a mutation ('Enable') but does not discuss reversibility, required permissions, failure modes, or asynchronous behavior. The description lacks important safety and side-effect 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?
Two sentences, efficient and front-loaded. No unnecessary words. Could be slightly more detailed without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 4 parameters and no output schema, the description does not mention return values, status of the operation, or error conditions. Lacks context about what happens after enabling (e.g., responder becomes available for execution).
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 parameters well. The description adds 'Provide configuration values for any required fields', which slightly reinforces the purpose of the configuration parameter but does not add new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Enable') and the resource ('a responder definition') with context ('in the current organization'). It distinguishes from siblings like 'cortex_disable_responder' and 'cortex_enable_analyzer', but could be more specific about enabling previously disabled responders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., when to enable vs. run a responder). Does not mention prerequisites like listing definitions first or checking configuration requirements via cortex_list_responder_definitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a specific analyzer by ID
| Name | Required | Description | Default |
|---|---|---|---|
| analyzerId | Yes | The analyzer ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies a safe read operation but gives no details on error handling, permissions, or return format. For a simple retrieval, it's adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. Every part contributes to purpose clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one required param, no output schema, no nested objects), the description covers the essential purpose. Could mention that it returns analyzer details, but 'Get details' suffices.
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% (analyzerId: 'The analyzer ID'). The description adds no extra meaning beyond 'by ID', which is already clear from the schema. Baseline 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 'Get details about a specific analyzer by ID' clearly states the action (get details), the resource (analyzer), and scope (specific, by ID). It distinguishes from sibling tools like cortex_list_analyzers (list all) and cortex_run_analyzer (run analyzer).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an analyzer ID and need details, but does not explicitly state when to use this over alternatives like cortex_list_analyzers or other get tools. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the status and details of an analysis job
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | The job ID to look up |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description implies a read-only operation via 'Get', but does not explicitly state safety, authentication requirements, or side effects. It adds minimal behavioral context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb, no extraneous words. Maximally concise while still conveying purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately states what the tool returns (status and details). It is complete enough for an agent to understand the basic function.
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% with the jobId parameter documented. The description adds no additional meaning beyond what the schema provides, so 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 verb 'Get' and resource 'status and details of an analysis job', which is specific and distinct from sibling tools like cortex_get_job_artifacts and cortex_get_job_report.
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 vs alternatives such as cortex_get_job_artifacts or cortex_get_job_report. The description does not mention usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get artifacts (extracted observables/IOCs) from a completed analysis job
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | The job ID to get artifacts for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the job must be completed but does not disclose error handling, response format, or whether the operation is read-only. Basic transparency is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's purpose with no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required param, no output schema, no annotations), the description covers the core functionality and a key constraint (completed job). It omits details like pagination or error handling but is generally sufficient for a well-understood 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 100% (one parameter with a clear description). The tool description adds no additional meaning 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 artifacts (IOCs) from a completed analysis job, using a specific verb and resource. It also implicitly differentiates from siblings like cortex_get_job and cortex_get_job_report.
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 after job completion ('from a completed analysis job') but does not explicitly state when to use this tool over alternatives or mention prerequisites or failure conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full report of a completed analysis job
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | The job ID to get the report for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the action but does not mention any behavioral traits (e.g., read-only, auth requirements, side effects). For a simple retrieval operation, the lack of detail is acceptable but not excellent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded and to the point. Every word is necessary and there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is mostly complete. It would benefit from mentioning that the job must be completed and from noting any differences from cortex_wait_and_get_report, but it suffices for basic 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?
Schema coverage is 100% and the parameter description is adequate. The tool description adds no additional meaning beyond what the schema already provides, so 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?
Clearly states the action ('Get'), the resource ('full report'), and the condition ('completed analysis job'). Distinguishes from sibling tools like cortex_get_job and cortex_get_job_artifacts by specifying 'full report' and 'completed'.
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?
Implies usage for completed jobs via the word 'completed', providing clear context. Does not explicitly state when not to use or name alternatives, but the condition is sufficient for basic guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a specific organization (requires superadmin API key)
| Name | Required | Description | Default |
|---|---|---|---|
| orgId | Yes | The organization ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the superadmin requirement but does not specify side effects, error handling, or rate limits. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, purpose is front-loaded. Every word adds 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 simple one-parameter read tool with no output schema, the description conveys the core purpose and auth requirement. Could hint at response fields, but not essential.
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 does not add parameter details beyond implying orgId specifies which organization. No format or constraints added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (Get) and resource (organization), includes a requirement (superadmin API key), and distinguishes from siblings like cortex_list_organizations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides the authentication prerequisite but lacks explicit when-not-to-use or alternative tool references. The requirement is clear but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Cortex instance health status, version info, and configuration
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a read-only operation (getting status), implying no side effects. However, it does not mention potential rate limits, authentication needs, or behavior if instance is down. Acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 9 words, front-loaded with action and resources. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (no parameters, no output schema), the description adequately covers the purpose. It could optionally mention output format for completeness, but the current description is sufficient for an agent to understand what the tool does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters (0 params, 100% schema coverage). Baseline for 0 params is 4. The description does not need to add parameter meaning, and it correctly omits any.
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 Cortex instance health status, version info, and configuration. Uses a specific verb ('Get') and specific resources, distinguishing it from siblings that deal with jobs, users, or analyzers.
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, no context on prerequisites or exclusions. It simply states functionality without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a specific user (requires superadmin API key)
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | The user login/ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the authorization requirement (superadmin API key) and implies a read-only operation ('Get details'), but does not explicitly state read-only, non-destructive behavior, or describe the format of the returned details. Additional context about what fields are returned would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the tool's purpose and critical usage condition. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one required parameter and no output schema. The description covers the purpose and auth requirement adequately for a simple retrieval tool, but lacks detail on what 'details' are returned (e.g., email, roles, organization). With no output schema, the agent lacks full context on expected output.
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 the 'userId' parameter already described as 'The user login/ID'. The description adds no further meaning, format, or examples beyond the schema, so it meets the baseline but provides no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get details about a specific user') and resource, and distinguishes from sibling tools like 'cortex_list_users' (list all) and 'cortex_create_user' (create). It also includes the required authorization context ('requires superadmin API key').
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 mentions the prerequisite of a superadmin API key, providing clear usage context. It does not explicitly state when not to use or name alternatives, but the purpose is so specific that alternatives are implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current API key for a user. Requires superadmin API key.
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | The user login/ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It states the operation is a get and requires superadmin, but does not disclose if the key is returned as plain text, any security implications, or that it is a read-only operation. More detail would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and 12 words, extremely concise and front-loaded. Every word provides value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description is fairly complete: it covers the action, resource, and auth requirement. However, it could mention what the response contains or edge cases like key expiration.
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 a description for userId. The description adds no additional meaning beyond the schema, making it baseline appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'current API key for a user'. It distinguishes from siblings like cortex_renew_user_key (renew vs get) and cortex_get_user (user info vs key).
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 states the requirement of 'superadmin API key', which is a key guideline for when to use this tool. It does not compare to alternatives or mention when not to use, but the context is clear for a simple get operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available analyzer definitions (installed but not necessarily enabled). Filter by data type or find analyzers that require no API keys.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (default: 50) | |
| search | No | Search analyzer names and descriptions (case-insensitive) | |
| dataType | No | Filter by supported data type (ip, domain, hash, url, file, mail, fqdn, etc.) | |
| freeOnly | No | If true, only return analyzers that require no configuration/API keys |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses the non-destructive read operation and the installed vs enabled distinction. However, it does not mention return format, pagination, or any rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the main purpose and filtering capability. It is concise and front-loaded, though could benefit from slightly more structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description omits return value hints and does not mention the limit parameter. It adequately covers purpose and filters but lacks completeness for a 4-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 4 parameters with 100% dedicated descriptions. The description summarizes two parameters (dataType, freeOnly) but adds little beyond the schema. Baseline 3 is appropriate as schema already clarifies 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 specifies the verb 'List', the resource 'analyzer definitions', and the scope 'installed but not necessarily enabled'. It also mentions filtering by data type and free-only analyzers, distinguishing it from sibling tools like cortex_list_analyzers which likely list only enabled analyzers.
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 viewing installed definitions but does not explicitly state when not to use it or compare to alternatives like cortex_list_analyzers. Some guidance is provided via filtering options, but no direct exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all enabled analyzers, optionally filtered by data type
| Name | Required | Description | Default |
|---|---|---|---|
| dataType | No | Filter by supported data type (ip, domain, hash, url, file, mail, fqdn, etc.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only adds 'enabled' and optional filter, but lacks details on output format, pagination, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded, no unnecessary words. Efficient and clear.
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, so description should clarify return format. Missing details on output structure, pagination, or default behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with description matching. Description adds no new meaning beyond schema's 'Filter by supported data type'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'list' verb, resource 'enabled analyzers', and optional filter. Distinguishes from siblings like cortex_get_analyzer (single) and cortex_list_analyzer_definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Usage is implied by name but no alternatives mentioned despite many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent analysis jobs with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of jobs to return (default: 50) | |
| status | No | Filter by status (Waiting, InProgress, Success, Failure, Deleted) | |
| dataType | No | Filter by data type | |
| analyzerName | No | Filter by analyzer name |
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 fails to mention pagination, ordering, side effects (none, but not stated), or what 'recent' means. This is insufficient for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. Could benefit from an additional sentence about typical usage or results, but current form is 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?
For a simple list tool with no output schema, the description is minimally adequate. However, it omits details like default limit (50), sorting, and result structure. Given low complexity, score 3.
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 covers 100% of parameters with descriptions. The description adds only 'optional filters', which is already implied by zero required parameters. No additional semantic value 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 'List recent analysis jobs with optional filters', specifying the verb (List) and resource (analysis jobs). It distinguishes from siblings like cortex_get_job (single job) but the term 'recent' is ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as cortex_get_job for specific jobs or cortex_get_job_report for reports. The description does not mention filtering capabilities or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all organizations (requires superadmin API key via CORTEX_SUPERADMIN_KEY)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the auth requirement, but does not explicitly state that it is a read-only operation or describe any side effects, rate limits, or pagination. More detail on the expected behavior would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action, and contains no fluff or redundant information. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should provide more context about the return format (e.g., list of organization objects) and whether there is pagination. It currently lacks this information, making it insufficient for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema, so the description does not need to add parameter information. The baseline score of 4 applies because schema coverage is 100% and no extra param context is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all organizations', which is a specific verb-resource pair. It distinguishes from sibling tools like cortex_get_organization (single) and cortex_create_organization (create). The auth hint ('requires superadmin API key') adds further clarity.
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 the required superadmin key, which implies when it can be used, but it does not explicitly compare with alternatives like cortex_get_organization or explain when this tool is preferable over other list commands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available responder definitions (installed but not necessarily enabled). Filter by data type or find responders that require no API keys.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (default: 50) | |
| search | No | Search responder names and descriptions (case-insensitive) | |
| dataType | No | Filter by supported data type (case, case_task, case_artifact, alert, etc.) | |
| freeOnly | No | If true, only return responders that require no configuration/API keys |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It mentions 'installed but not necessarily enabled' and filtering, but lacks details on pagination, ordering, response format, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loaded with main action. Efficient and clear without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should hint at return format. It does not mention what fields are returned for definitions. Missing error handling or pagination behavior. Incomplete for a list tool with 4 parameters.
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 'Filter by data type or find responders that require no API keys', which aligns with dataType and freeOnly parameters but does not add new information 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 'List all available responder definitions (installed but not necessarily enabled)' with specific verbs and resource. It distinguishes from sibling tools like cortex_list_responders (likely lists enabled ones) and cortex_list_analyzer_definitions.
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 browsing available responders, but does not explicitly state when to use this vs. alternatives like cortex_list_responders or other list tools. No exclusions or prerequisites provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all enabled responders, optionally filtered by data type
| Name | Required | Description | Default |
|---|---|---|---|
| dataType | No | Filter by supported data type |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only states the basic function without disclosing behavioral traits such as return format, pagination, rate limits, or the meaning of 'enabled'. This lack of detail leaves an agent uncertain about the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single, front-loaded sentence with no unnecessary words. It efficiently conveys the tool's purpose and optional filter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema), the description provides a minimal but adequate overview. However, it lacks details about the return structure or any pagination, making it slightly incomplete for complex use cases.
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 the 'dataType' parameter. The description's mention of 'optionally filtered by data type' adds no new meaning beyond what the schema provides, leading to a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'enabled responders', and the optional filter by data type. It effectively distinguishes from siblings like 'cortex_list_analyzers' (for analyzers) and 'cortex_list_responder_definitions' (for definitions, not just enabled).
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 (listing enabled responders with optional filtering) but does not provide explicit when-to-use or when-not-to-use guidance compared to sibling tools. There is no mention of alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all users across organizations (requires superadmin API key via CORTEX_SUPERADMIN_KEY)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only reveals the authorization trait but does not mention return format, pagination, or other behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no parameters and no output schema, the description covers the core purpose and auth requirement, but lacks information about response format or data volume.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is effectively 100%. The description adds no param-specific info, but the baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'all users across organizations', distinguishing it from siblings like cortex_get_user (single user) and cortex_create_user (creation).
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 the requirement of a superadmin API key, indicating when to use, but does not mention alternatives for non-superadmin users or context for 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.
Generate a new API key for a user (invalidates the previous key). Requires superadmin API key.
| Name | Required | Description | Default |
|---|---|---|---|
| userId | Yes | The user login/ID to renew the key for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important side effects (invalidates previous key) and permission requirements (superadmin). No annotations are provided, so description carries the burden; it does so effectively for a simple mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two sentences that cover purpose, side effect, and permission. No unnecessary words; every sentence adds 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?
Given the tool's simplicity (single required parameter, no output schema), the description fully covers what an agent needs: action, side effect, and authentication requirement. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema adequately describes the userId parameter. The description adds no extra semantic beyond what is already in the schema, meeting the baseline but not exceeding.
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 generates a new API key for a user and invalidates the previous key. The verb 'generate' and resource 'API key for a user' are specific, and it distinguishes itself from sibling tools like cortex_get_user_key.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions requirement for superadmin API key, providing clear context. Does not explicitly list when not to use or alternatives, but the purpose is self-evident given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit an observable to a specific analyzer for analysis
| Name | Required | Description | Default |
|---|---|---|---|
| pap | Yes | Permissible Actions Protocol level (0-3) | |
| tlp | Yes | Traffic Light Protocol level (0=WHITE, 1=GREEN, 2=AMBER, 3=RED) | |
| data | Yes | The observable value (IP, domain, hash, URL, etc.) | |
| message | No | Optional context message for the analysis | |
| dataType | Yes | The observable data type | |
| analyzerId | Yes | The analyzer ID to run |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It does not disclose behavioral traits such as whether the analysis is synchronous, how to obtain results, or any authentication or rate limit implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded with the key action, though it lacks structure for additional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters (5 required), no output schema, and no annotations, the description is too brief. It does not explain how to interpret the result or any prerequisites for using the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of parameter descriptions. The description adds no additional meaning beyond the schema, which is the baseline expectation.
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 specifies the action ('submit'), the resource ('observable to analyzer'), and the purpose ('analysis'). It is clear but does not differentiate from sibling tools like cortex_analyze_observable or cortex_run_analyzer_by_name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There are many sibling tools for running analyzers, and the description offers no context on selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an analyzer by name instead of ID (convenience wrapper)
| Name | Required | Description | Default |
|---|---|---|---|
| pap | No | Permissible Actions Protocol level (default: 2) | |
| tlp | No | Traffic Light Protocol level (default: 2/AMBER) | |
| data | Yes | The observable value | |
| dataType | Yes | The observable data type | |
| analyzerName | Yes | The analyzer name to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It fails to mention any side effects, authentication needs, rate limits, or error states (e.g., what happens if the analyzer name is not found). The minimal description does not adequately disclose behavioral traits beyond the basic 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, clear sentence with no unnecessary words. It is efficiently front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and is a mutation (runs an analyzer), the description is too brief. It lacks information about return values, job creation, error handling, and expected behavior, making it incomplete for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so baseline is 3. The description adds no additional meaning to parameters beyond what is already in the schema (e.g., analyzerName, dataType, data). It does not clarify syntax, formats, or relationships.
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 runs an analyzer by name instead of ID, which is a specific verb-resource pair. It also distinguishes from the sibling tool cortex_run_analyzer by explicitly contrasting name vs ID.
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 labels the tool a 'convenience wrapper', implying it is an alternative to cortex_run_analyzer (ID-based), but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention any prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a file to a specific analyzer for analysis. Provide a file path or base64-encoded content.
| Name | Required | Description | Default |
|---|---|---|---|
| pap | No | Permissible Actions Protocol level (0-3) | |
| tlp | No | Traffic Light Protocol level (0=WHITE, 1=GREEN, 2=AMBER, 3=RED) | |
| message | No | Optional context message for the analysis | |
| filePath | No | Path to the file to analyze. Confined to the CORTEX_FILE_BASE_DIR directory; paths outside it (or filesystem reads when CORTEX_FILE_BASE_DIR is unset) are refused. Use fileBase64 for arbitrary content. | |
| filename | No | Filename (required with fileBase64, auto-detected from filePath) | |
| analyzerId | Yes | The analyzer ID to run | |
| fileBase64 | No | Base64-encoded file content (alternative to filePath) | |
| contentType | No | MIME type of the file (default: application/octet-stream) | application/octet-stream |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the burden falls on the description. It only says 'submit for analysis' without disclosing behavioral traits like error handling, permissions, rate limits, or whether the analysis is synchronous. This is insufficient for a mutation-like tool.
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, readable sentence that conveys the essential action. It is efficient with no redundant words, though it could be slightly more structured by separating the two input methods into separate clauses.
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 8 parameters and no output schema, the description is too minimal. It does not explain relationships (e.g., filePath vs fileBase64 mutual exclusivity), constraints (filePath confined to directory), or required combinations (filename with fileBase64). The schema covers details but the description lacks synthesis.
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 each parameter. The description adds a high-level overview ('provide a file path or base64-encoded content') but does not add meaning beyond what the schema provides, so 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?
The description clearly states the action ('submit a file') and the resource ('to a specific analyzer'), and specifies two input methods (file path or base64). This distinguishes it from sibling tools like cortex_run_analyzer which likely handle observables.
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 providing a file path or base64 content but does not give guidance on when to use this tool versus alternatives (e.g., cortex_run_analyzer for observables) or when not to use it. No exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a responder action against a TheHive entity (case, task, artifact, alert). DESTRUCTIVE: responders perform real-world side effects (blocking IPs, sending mail, isolating hosts). Gated behind the CORTEX_ALLOW_DESTRUCTIVE env var AND confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Must be set to true to actually run the responder. Defaults to false as a safety guard against accidental side effects. | |
| objectId | Yes | The ID of the entity from TheHive | |
| objectType | Yes | The type of TheHive entity to act on | |
| parameters | No | Optional responder-specific parameters | |
| responderId | Yes | The responder ID to execute |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly labels the tool as DESTRUCTIVE and explains real-world side effects and gating conditions, which is clear. However, it does not mention whether the action is asynchronous or what the return behavior is.
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 fluff. Every sentence adds value, addressing purpose, subject, and key behavioral guardrails.
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 lack of output schema, the description covers essential behavioral aspects (destructive, guardrails) but does not explain what the tool returns (likely a job object) or how it integrates with the overall workflow. It is adequate but not fully 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 context for the 'confirm' parameter (must be true to run) and 'parameters' (responder-specific), but these details are already partially in the schema. The added value is marginal.
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 purpose: 'Execute a responder action against a TheHive entity (case, task, artifact, alert).' It distinguishes itself from sibling tools like cortex_run_analyzer by explicitly mentioning 'responder' and the entity types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that the tool is gated behind CORTEX_ALLOW_DESTRUCTIVE env var and confirm=true, but it does not explicitly state when to use this tool versus alternatives (e.g., run_analyzer) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an organization's description or status (requires superadmin API key)
| Name | Required | Description | Default |
|---|---|---|---|
| orgId | Yes | The organization ID or name | |
| status | No | New status: "Active" or "Locked" | |
| description | No | New description for the organization |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description only notes the superadmin requirement. Does not disclose side effects, mutability, or behavior for omitted fields. Lacks detail beyond auth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and resource, followed by auth requirement. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential purpose and auth, but lacks return value info (no output schema) and usage context. Adequate for a simple update 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 descriptions cover all 3 parameters (100%). Description adds minimal extra meaning by summarizing 'description or status', but no format or constraints 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?
Clearly states the action ('Update'), the resource ('organization'), and specific updatable fields ('description or status'). Distinct from sibling tools like cortex_create_organization and cortex_get_organization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Only mentions a prerequisite (superadmin API key) but does not explain context or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for a job to complete and return the full report (with polling timeout)
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | The job ID to wait for | |
| timeout | No | Timeout in seconds (default: 300, max: 3600) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions polling timeout but does not detail polling behavior, timeout handling, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise, front-loaded with key action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, description is incomplete; missing details on polling interval, timeout behavior, and error states.
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%, and description does not add extra meaning beyond what the schema already provides for jobId and timeout.
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 verb (wait for and return) and resource (full report), distinguishing it from siblings like cortex_get_job_report which likely returns immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage can be inferred (use when job is in progress) but lacks explicit when-to-use or when-not-to-use instructions, nor comparison to alternatives.
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.3.3cortex_analyze_observable4 fields changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"Input schema / properties / analyzersAdded value: +{
+ "description": "Explicit allowlist of analyzer names (substring match, case-insensitive) to run. Required unless fanOut=true. Only matching analyzers that also support the data type are submitted.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / fanOutAdded value: +{
+ "default": false,
+ "description": "If true, submit the observable to ALL applicable analyzers (capped by maxAnalyzers / CORTEX_MAX_FANOUT). Default false: you must pass an `analyzers` allowlist.",
+ "type": "boolean"
+}Input schema / properties / maxAnalyzersAdded value: +{
+ "description": "Hard cap on how many analyzers to run this call. Defaults to and is clamped by the server's CORTEX_MAX_FANOUT (default 10).",
+ "maximum": 9007199254740991,
+ "minimum": 1,
+ "type": "integer"
+}cortex_cleanup_jobs1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_create_organization1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_create_user1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_delete_job2 fields changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"Input schema / properties / confirmAdded value: +{
+ "default": false,
+ "description": "Must be set to true to actually delete the job. Defaults to false as a safety guard.",
+ "type": "boolean"
+}cortex_disable_analyzer2 fields changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"Input schema / properties / confirmAdded value: +{
+ "default": false,
+ "description": "Must be set to true to actually disable/remove the analyzer. Defaults to false as a safety guard.",
+ "type": "boolean"
+}cortex_disable_responder1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_enable_analyzer1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_enable_responder1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_get_analyzer1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_get_job1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_get_job_artifacts1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_get_job_report1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_get_organization1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_get_status1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_get_user1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_get_user_key1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_list_analyzer_definitions1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_list_analyzers1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_list_jobs1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_list_organizations1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_list_responder_definitions1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_list_responders1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_list_users1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_renew_user_key1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_run_analyzer1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_run_analyzer_by_name1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_run_analyzer_file2 fields changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"Input schema / properties / filePath / descriptionPrevious value: -"Path to the file to analyze (local filesystem)"New value: +"Path to the file to analyze. Confined to the CORTEX_FILE_BASE_DIR directory; paths outside it (or filesystem reads when CORTEX_FILE_BASE_DIR is unset) are refused. Use fileBase64 for arbitrary content."cortex_run_responder2 fields changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"Input schema / properties / confirmAdded value: +{
+ "default": false,
+ "description": "Must be set to true to actually run the responder. Defaults to false as a safety guard against accidental side effects.",
+ "type": "boolean"
+}cortex_update_organization1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"cortex_wait_and_get_report1 field changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"v1.2.0cortex_analyze_observable6 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / data / descriptionPrevious value: -"The observable value"New value: +"The observable value (IP, domain, hash, URL, email, etc.)"Input schema / properties / dataType / descriptionPrevious value: -"The observable data type (ip, domain, hash, url, etc.)"New value: +"The observable data type. If omitted, will be auto-detected from the value."Input schema / properties / pap / descriptionPrevious value: -"Permissible Actions Protocol level (default: 2)"New value: +"Permissible Actions Protocol level (0-3). Default: 2"Input schema / properties / tlp / descriptionPrevious value: -"Traffic Light Protocol level (default: 2/AMBER)"New value: +"Traffic Light Protocol level (0=WHITE, 1=GREEN, 2=AMBER, 3=RED). Default: 2/AMBER"Input schema / requiredPrevious value: -[
- "dataType",
- "data"
-]New value: +[
+ "data"
+]cortex_cleanup_jobscortex_create_organizationcortex_create_usercortex_delete_jobcortex_disable_analyzercortex_disable_respondercortex_enable_analyzercortex_enable_respondercortex_get_analyzer1 field changedInput schema / additionalPropertiesRemoved value: -falsecortex_get_job1 field changedInput schema / additionalPropertiesRemoved value: -falsecortex_get_job_artifacts1 field changedInput schema / additionalPropertiesRemoved value: -falsecortex_get_job_report1 field changedInput schema / additionalPropertiesRemoved value: -falsecortex_get_organizationcortex_get_statuscortex_get_usercortex_get_user_keycortex_list_analyzer_definitionscortex_list_analyzers1 field changedInput schema / additionalPropertiesRemoved value: -falsecortex_list_jobs1 field changedInput schema / additionalPropertiesRemoved value: -falsecortex_list_organizationscortex_list_responder_definitionscortex_list_responders1 field changedInput schema / additionalPropertiesRemoved value: -falsecortex_list_userscortex_renew_user_keycortex_run_analyzer1 field changedInput schema / additionalPropertiesRemoved value: -falsecortex_run_analyzer_by_name1 field changedInput schema / additionalPropertiesRemoved value: -falsecortex_run_analyzer_filecortex_run_responder2 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / parameters / propertyNamesAdded value: +{
+ "type": "string"
+}cortex_update_organizationcortex_wait_and_get_report1 field changedInput schema / additionalPropertiesRemoved value: -falsev1.0.0cortex_analyze_observablecortex_get_analyzercortex_get_jobcortex_get_job_artifactscortex_get_job_reportcortex_list_analyzerscortex_list_jobscortex_list_responderscortex_run_analyzercortex_run_analyzer_by_namecortex_run_respondercortex_wait_and_get_reportScored across 31 tools
Each tool has a clearly distinct purpose: analyzers, responders, jobs, organizations, and users are separate domains. Within each, operations are unique (list, get, create, update, delete, enable, disable, run). Descriptions clarify any potential overlap, e.g., cortex_analyze_observable vs cortex_run_analyzer.
All tools follow a consistent `cortex_verb_noun` pattern with snake_case. Verbs like list, get, create, run are used uniformly. Even compound verbs like `wait_and_get` fit the pattern. No mixing of styles.
With 31 tools, this is a large set, but each tool corresponds to a specific operation in the Cortex security analysis platform. The count is slightly above the typical well-scoped range but justified by the platform's complexity and the need to cover analyzers, responders, jobs, organizations, and users.
The tool set covers core CRUD operations for analyzers, responders, jobs, organizations, and users. Notable gaps include missing delete tools for users and organizations, and no update for users besides key renewal. But the main analysis workflow is fully covered, and the gaps are minor.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
