MCP Dashboard
Scoped Model Context Protocol Servers
MCP Server Catalogue
Each server exposes a scoped set of tools over the stateless MCP JSON-RPC transport.
Clients connect by posting tools/list or tools/call to the endpoint below.
Authentication. The transport accepts both Cobrainer JWTs and Cobrainer API keys ?
send JWTs as a Bearer token in the Authorization header and API keys in the
X-API-Key header. The listed authority on the credential gates which server can be
reached; per-tool checks (e.g. reviewer assignment) run on invocation.
Knowledge Base
Read
Knowledge Base
Read
-
cobrainer_document_searchSearch Cobrainer's product and methodology documentation for passages relevant to a free-text query. Use it to ground answers about Cobrainer features, terminology and best practices. This documentation is global rather than tenant-specific. Returns relevance-ordered text in 'chunks', or empty when nothing matched.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","description":"Free-text retrieval query (1-1000 chars)."},"numberOfResults":{"type":"integer","format":"int32","description":"Results to return (1-100). Defaults to 5."}},"required":["query"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chunks":{"type":"array","items":{"type":"string"}},"paradigms":{"type":"array","items":{"type":"string"}},"results":{"type":"array","items":{"type":"object","properties":{"chunk_index":{"type":["integer","null"],"format":"int32"},"document_id":{"type":["string","null"]},"graph_context":{"type":["object","null"],"properties":{"entities":{"type":"array","items":{"type":"object","properties":{"disputed":{"type":"boolean"},"id":{"type":"string"},"name":{"type":["string","null"]}}}}}},"paradigms":{"type":"array","items":{"type":"string"}},"scores":{"type":"object","properties":{"graph":{"type":["number","null"],"format":"double"},"lexical":{"type":["number","null"],"format":"double"},"rerank":{"type":["number","null"],"format":"double"},"rrf":{"type":["number","null"],"format":"double"},"vector":{"type":["number","null"],"format":"double"}}},"text":{"type":"string"}}}}}} -
knowledge_base_chunk_contextFetch the chunks surrounding one you already found via 'knowledge_base_search' or 'knowledge_base_expand_entity' ? a pure document-structure lookup, no new search. Use it when a retrieved chunk looks relevant but truncated. Provide the 'documentId' and 'chunkIndex' from a prior result. Returns the anchor plus up to 'window' neighbours on each side, ascending by chunk_index; empty if the anchor does not exist for this tenant.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"documentId":{"type":"string","description":"document_id from a prior knowledge_base_search / knowledge_base_expand_entity result."},"chunkIndex":{"type":"integer","format":"int32","description":"chunk_index of the anchor chunk within that document."},"window":{"type":"integer","format":"int32","description":"Chunks to fetch on each side of the anchor (0-10). Defaults to 2."}},"required":["documentId","chunkIndex"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"chunk_index":{"type":"integer","format":"int32"},"text":{"type":"string"}}}},"document_id":{"type":["string","null"]}}} -
knowledge_base_expand_entityWalk the tenant knowledge graph one deliberate step from an entity id surfaced in a 'knowledge_base_search' result's 'graph_context.entities[].id'. Returns entities (with 'assertion', 'confidence', 'disputed', 'depth') and relations, each with provenance 'chunks'; feed a chunk's 'document_id'/'chunk_index' into 'knowledge_base_chunk_context' for more context. Returns an empty result (not an error) for unknown ids.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entityId":{"type":"string","description":"Entity id from a knowledge_base_search result's graph_context.entities[].id."},"depth":{"type":"integer","format":"int32","description":"Hops to walk from the anchor (1-3). Defaults to 1."},"chunkLimit":{"type":"integer","format":"int32","description":"Max provenance chunks per entity/relation (0-50; 0 = structure only). Defaults to 5."}},"required":["entityId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"ExpandChunk":{"type":"object","properties":{"chunk_id":{"type":["string","null"]},"chunk_index":{"type":["integer","null"],"format":"int32"},"document_id":{"type":["string","null"]},"text":{"type":"string"}}}},"type":"object","properties":{"entities":{"type":"array","items":{"type":"object","properties":{"assertion":{"type":["string","null"]},"chunks":{"type":"array","items":{"$ref":"#/$defs/ExpandChunk"}},"confidence":{"type":["number","null"],"format":"double"},"depth":{"type":["integer","null"],"format":"int32"},"disputed":{"type":"boolean"},"id":{"type":"string"},"kind":{"type":["string","null"]},"name":{"type":["string","null"]}}}},"relations":{"type":"array","items":{"type":"object","properties":{"chunks":{"type":"array","items":{"$ref":"#/$defs/ExpandChunk"}},"confidence":{"type":["number","null"],"format":"double"},"from":{"type":["string","null"]},"id":{"type":"string"},"kind":{"type":["string","null"]},"to":{"type":["string","null"]}}}}}} -
knowledge_base_searchSearch the tenant's knowledge base using hybrid vector, lexical (BM25), and graph retrieval. Returns index-aligned 'results' with document, score, and graph context. Use 'knowledge_base_chunk_context' for surrounding text and 'knowledge_base_expand_entity' for graph traversal. Returns empty when nothing matched.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","description":"Free-text retrieval query (1-1000 chars)."},"numberOfResults":{"type":"integer","format":"int32","description":"Results to return after fusion/rerank (1-100). Defaults to 5."},"paradigms":{"type":"array","items":{"type":"string"},"description":"Methods to fuse (vector, lexical, graph). Omit for all three."},"rerank":{"type":"boolean","description":"Whether to rerank. Defaults to true."}},"required":["query"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"chunks":{"type":"array","items":{"type":"string"}},"paradigms":{"type":"array","items":{"type":"string"}},"results":{"type":"array","items":{"type":"object","properties":{"chunk_index":{"type":["integer","null"],"format":"int32"},"document_id":{"type":["string","null"]},"graph_context":{"type":["object","null"],"properties":{"entities":{"type":"array","items":{"type":"object","properties":{"disputed":{"type":"boolean"},"id":{"type":"string"},"name":{"type":["string","null"]}}}}}},"paradigms":{"type":"array","items":{"type":"string"}},"scores":{"type":"object","properties":{"graph":{"type":["number","null"],"format":"double"},"lexical":{"type":["number","null"],"format":"double"},"rerank":{"type":["number","null"],"format":"double"},"rrf":{"type":["number","null"],"format":"double"},"vector":{"type":["number","null"],"format":"double"}}},"text":{"type":"string"}}}}}}
Job Architecture
Read
Job Architecture
Read
-
find_similar_role_versionsSemantic similarity search over job ROLE version profiles only. Given an existing job role version, returns the topK most similar roles across the tenant's job architecture, ranked by cosine similarity over Cohere embed-v4 embeddings of the role's job profile content. Matches are comparable reference roles (similarity >= 0.5), not necessarily duplicates ? scores above ~0.95 indicate near-identical profiles. Returns lightweight hits (ids, titles, translations, score); fetch full profile content via 'list_job_architecture_versions' when needed. Useful during role review to surface comparable roles as reference. The source role itself is excluded. Returns an empty list if the source item is not a role ? levels, clusters and families are not covered.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID whose role embeddings to search against."},"roleId":{"type":"string","description":"Source role UUID."},"version":{"type":"integer","format":"int32","description":"Source role version number."},"topK":{"type":"integer","format":"int32","description":"Max hits. Defaults to 3, capped at 25."}},"required":["jobArchitectureId","roleId","version"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"jobArchitectureId":{"type":"string"},"jobArchitectureTitle":{"type":"string"},"layer":{"type":"string","description":"'FAMILY', 'CLUSTER' or 'ROLE'."},"similarityScore":{"type":"number","format":"double","description":"Cosine similarity; higher = more similar."},"title":{"type":"string","description":"English title."},"translations":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"description":"On families/clusters this is the main descriptive text ('structured' is always null there). On roles/levels it is only an internal working summary: machine-translated languages leave it blank ? blank is normal, not missing content ? and the profile content users see lives in 'structured' (which may itself contain a section named 'Description')."},"language":{"type":"string","description":"BCP-47 tag (e.g. 'en-US')."},"structured":{"description":"Content sections (e.g. responsibilities, qualifications); TASKS sections are excluded, see 'tasks'. Pass verbatim back to 'update_job_role' / 'update_job_level' on a partial edit to preserve them.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string"}},"required":["language","title"]}}},"required":["itemId","jobArchitectureId","jobArchitectureTitle","layer","similarityScore","title","translations"]}}},"required":["items"]} -
get_active_cobrainer_job_profile_templateReturn the Cobrainer-managed job profile template that takes precedence ? the one marked as the default, or the most recently activated one when no default is set ? or an envelope with a null template when none is active. English text only on output. If null, the agent must surface this to the user instead of authoring template content blindly.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpCobrainerTemplateSectionView":{"type":"object","properties":{"contentType":{"type":"string","description":"BULLET_POINTS, SENTENCES or TASKS."},"guidance":{"type":"string","description":"Follow when authoring this section."},"maxNumberOfItems":{"type":"integer","format":"int32"},"minNumberOfItems":{"type":"integer","format":"int32"},"name":{"type":"string"},"sectionId":{"type":"string","description":"Use as the 'tag' when authoring structured content."}},"required":["contentType","guidance","maxNumberOfItems","minNumberOfItems","name","sectionId"]},"McpSkillLimits":{"type":"object","properties":{"expectedNumberOfSkills":{"type":"integer","format":"int32","description":"Target skill count ? aim for this when detecting skills."},"maximumNumberOfSkills":{"type":"integer","format":"int32","description":"Hard cap."},"skillDetectionPreference":{"type":["string","null"],"description":"Free-text soft preference biasing skill detection (max 5000 chars)."}},"required":["expectedNumberOfSkills","maximumNumberOfSkills"]}},"type":"object","properties":{"template":{"type":["object","null"],"properties":{"activatedAt":{"type":["string","null"],"format":"date-time","description":"Null = never activated."},"createdAt":{"type":"string","format":"date-time"},"description":{"type":"string"},"jobLevelSections":{"type":"array","items":{"$ref":"#/$defs/McpCobrainerTemplateSectionView"}},"jobRoleSections":{"type":"array","items":{"$ref":"#/$defs/McpCobrainerTemplateSectionView"}},"levelSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"name":{"type":"string"},"roleSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"status":{"type":"string","description":"DRAFT, ACTIVE or DEPRECATED."},"templateId":{"type":"string"}},"required":["createdAt","description","jobLevelSections","jobRoleSections","levelSkillLimits","name","roleSkillLimits","status","templateId"],"description":"Null = none active ? surface this to the user and do not author template content blindly."}}} -
get_cobrainer_job_profile_template_by_idFetch a single Cobrainer-managed (system) job profile template by id. Returns {template: null} when the id is unknown. English text only on output.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"templateId":{"type":"string","description":"Cobrainer template UUID."}},"required":["templateId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpCobrainerTemplateSectionView":{"type":"object","properties":{"contentType":{"type":"string","description":"BULLET_POINTS, SENTENCES or TASKS."},"guidance":{"type":"string","description":"Follow when authoring this section."},"maxNumberOfItems":{"type":"integer","format":"int32"},"minNumberOfItems":{"type":"integer","format":"int32"},"name":{"type":"string"},"sectionId":{"type":"string","description":"Use as the 'tag' when authoring structured content."}},"required":["contentType","guidance","maxNumberOfItems","minNumberOfItems","name","sectionId"]},"McpSkillLimits":{"type":"object","properties":{"expectedNumberOfSkills":{"type":"integer","format":"int32","description":"Target skill count ? aim for this when detecting skills."},"maximumNumberOfSkills":{"type":"integer","format":"int32","description":"Hard cap."},"skillDetectionPreference":{"type":["string","null"],"description":"Free-text soft preference biasing skill detection (max 5000 chars)."}},"required":["expectedNumberOfSkills","maximumNumberOfSkills"]}},"type":"object","properties":{"template":{"type":["object","null"],"properties":{"activatedAt":{"type":["string","null"],"format":"date-time","description":"Null = never activated."},"createdAt":{"type":"string","format":"date-time"},"description":{"type":"string"},"jobLevelSections":{"type":"array","items":{"$ref":"#/$defs/McpCobrainerTemplateSectionView"}},"jobRoleSections":{"type":"array","items":{"$ref":"#/$defs/McpCobrainerTemplateSectionView"}},"levelSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"name":{"type":"string"},"roleSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"status":{"type":"string","description":"DRAFT, ACTIVE or DEPRECATED."},"templateId":{"type":"string"}},"required":["createdAt","description","jobLevelSections","jobRoleSections","levelSkillLimits","name","roleSkillLimits","status","templateId"],"description":"Null = unknown template id."}}} -
get_commentsList user comments on a single role or level. By default returns the OPEN, non-stale comments of the requested version across all source languages (a comment counts as resolved only once it was resolved in that version or earlier ? one resolved later still shows as open here). Each comment carries what it is attached to (title, skill, or a description section); a section comment also carries the 'quotedText' the user highlighted and its 'anchorStatus' ? 'anchored' means that text still exists, 'unresolved' that it is gone, 'ambiguous' that it now occurs in more than one place. 'unresolved' and 'ambiguous' section comments are stale and are omitted unless 'includeStale' is set. Replies are included and follow the parent: each reply carries the 'parentCommentId' of the comment it answers, and replies of a hidden thread are hidden with it. Each comment also carries 'authorName' and 'authorId'. The role/level edit flow already injects the open, anchored comments across all source languages; call this tool to also see resolved comments ('includeResolved') or stale ones ('includeStale'), or to narrow to one 'language'. Comment ids match those used elsewhere in the job architecture.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID the role/level belongs to."},"itemId":{"type":"string","description":"UUID of the role or level whose comments to list."},"language":{"type":"string","description":"Optional BCP-47 source-language tag (e.g. 'de-DE'). Omit to return comments in every source language."},"includeResolved":{"type":"boolean","description":"Include resolved/closed comments too. Defaults to false (only open comments)."},"version":{"type":"integer","format":"int32","description":"Version number to read comments for. Omit to use the current version (published, else reviewed, else latest)."},"includeStale":{"type":"boolean","description":"Include stale section comments ('unresolved'/'ambiguous' anchor) too. Defaults to false."}},"required":["jobArchitectureId","itemId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"comments":{"description":"Flattened: a reply carries the 'parentCommentId' of the comment it answers.","type":"array","items":{"type":"object","properties":{"anchorStatus":{"type":["string","null"],"description":"Vs current content: 'anchored' (highlighted text still exists), 'unresolved' (not found) or 'ambiguous' (matches more than one place). Treat 'unresolved'/'ambiguous' as stale ? do not act on them unless the user explicitly refers to them. Null for 'title'/'skill' comments."},"authorId":{"type":["string","null"]},"authorName":{"type":["string","null"]},"commentId":{"type":"string"},"content":{"type":"string"},"language":{"type":"string","description":"BCP-47 tag."},"parentCommentId":{"type":["string","null"],"description":"Null = top-level comment."},"quotedText":{"type":["string","null"],"description":"Text the user highlighted ? what the feedback is about."},"resolved":{"type":"boolean"},"resolvedInVersion":{"type":["integer","null"],"format":"int32","description":"Version that resolved the thread. Null = open."},"sectionId":{"type":["string","null"],"description":"Only for 'description-section'."},"skillId":{"type":["string","null"],"description":"Only for 'skill'."},"stepIndex":{"type":["integer","null"],"format":"int32","description":"Only for work-task workflow-step targets."},"targetKind":{"type":"string","description":"Profile or work-task target kind."},"version":{"type":["integer","null"],"format":"int32","description":"Content version the comment targets."}},"required":["commentId","content","language","resolved","targetKind"]}}}} -
get_current_job_architecture_versionFetch the current (published-or-latest) version of a given job role or job level. Returns {version: null} when the architecture or item is unknown.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."}},"required":["jobArchitectureId","itemId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpJobProfileContentElementInput":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"type":"object","properties":{"version":{"type":["object","null"],"properties":{"comment":{"type":["string","null"]},"competencies":{"description":"Referenced by the skills' 'competencyId'.","type":"array","items":{"type":"object","properties":{"competencyId":{"type":"string","description":"Referenced by the grouped skills' 'competencyId'."},"description":{"type":["string","null"]},"title":{"type":"string","description":"Falls back to English when untranslated."}},"required":["competencyId","title"]}},"englishDescription":{"type":["string","null"],"description":"Internal working summary, not part of the rendered profile. Often blank ? blank is normal, not missing content. The profile content users see lives in 'englishStructured'."},"englishStructured":{"description":"English content sections. Pass verbatim back to 'update_job_role' / 'update_job_level' on a partial edit to preserve them.","type":["array","null"],"items":{"$ref":"#/$defs/McpJobProfileContentElementInput"}},"englishTitle":{"type":"string","description":"Empty when no English translation exists."},"itemId":{"type":"string","description":"Role or level UUID."},"jobArchitectureId":{"type":"string"},"layer":{"type":"string","description":"'ROLE' or 'LEVEL'."},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Null = still draft."},"reviewedAt":{"type":["string","null"],"format":"date-time","description":"Null = unreviewed."},"sectionTags":{"type":["array","null"],"items":{"type":"object","properties":{"names":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 tag."},"text":{"type":"string"}},"required":["language","text"]}},"sectionId":{"type":"string","description":"Matches the 'id' of structured content elements in this section."},"type":{"type":"string","description":"Content format: BULLET_POINTS, SENTENCES or TASKS. TASKS content lives in 'tasks'; never author structured text for it."}},"required":["names","sectionId"]}},"skills":{"type":"array","items":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Matches an entry in 'competencies'. Null = ungrouped."},"id":{"type":"string","description":"Skill UUID."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillType":{"type":["string","null"],"description":"hard, soft or language."},"title":{"type":"string"}},"required":["id","level","title"]}},"translations":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"description":"On families/clusters this is the main descriptive text ('structured' is always null there). On roles/levels it is only an internal working summary: machine-translated languages leave it blank ? blank is normal, not missing content ? and the profile content users see lives in 'structured' (which may itself contain a section named 'Description')."},"language":{"type":"string","description":"BCP-47 tag (e.g. 'en-US')."},"structured":{"description":"Content sections (e.g. responsibilities, qualifications); TASKS sections are excluded, see 'tasks'. Pass verbatim back to 'update_job_role' / 'update_job_level' on a partial edit to preserve them.","type":["array","null"],"items":{"$ref":"#/$defs/McpJobProfileContentElementInput"}},"title":{"type":"string"}},"required":["language","title"]}},"version":{"type":"integer","format":"int32","description":"Monotonically increasing, starting at 1."}},"required":["englishTitle","itemId","jobArchitectureId","layer","skills","translations","version"],"description":"Null = unknown architecture, item or version."}}} -
get_job_architecture_versionFetch a specific version of a job role or job level by architectureId, itemId and version number. Returns the English title and description, skills and publish/review state. Returns {version: null} when the architecture, item or version is unknown.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"version":{"type":"integer","format":"int32","description":"Version number."}},"required":["jobArchitectureId","itemId","version"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpJobProfileContentElementInput":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"type":"object","properties":{"version":{"type":["object","null"],"properties":{"comment":{"type":["string","null"]},"competencies":{"description":"Referenced by the skills' 'competencyId'.","type":"array","items":{"type":"object","properties":{"competencyId":{"type":"string","description":"Referenced by the grouped skills' 'competencyId'."},"description":{"type":["string","null"]},"title":{"type":"string","description":"Falls back to English when untranslated."}},"required":["competencyId","title"]}},"englishDescription":{"type":["string","null"],"description":"Internal working summary, not part of the rendered profile. Often blank ? blank is normal, not missing content. The profile content users see lives in 'englishStructured'."},"englishStructured":{"description":"English content sections. Pass verbatim back to 'update_job_role' / 'update_job_level' on a partial edit to preserve them.","type":["array","null"],"items":{"$ref":"#/$defs/McpJobProfileContentElementInput"}},"englishTitle":{"type":"string","description":"Empty when no English translation exists."},"itemId":{"type":"string","description":"Role or level UUID."},"jobArchitectureId":{"type":"string"},"layer":{"type":"string","description":"'ROLE' or 'LEVEL'."},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Null = still draft."},"reviewedAt":{"type":["string","null"],"format":"date-time","description":"Null = unreviewed."},"sectionTags":{"type":["array","null"],"items":{"type":"object","properties":{"names":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 tag."},"text":{"type":"string"}},"required":["language","text"]}},"sectionId":{"type":"string","description":"Matches the 'id' of structured content elements in this section."},"type":{"type":"string","description":"Content format: BULLET_POINTS, SENTENCES or TASKS. TASKS content lives in 'tasks'; never author structured text for it."}},"required":["names","sectionId"]}},"skills":{"type":"array","items":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Matches an entry in 'competencies'. Null = ungrouped."},"id":{"type":"string","description":"Skill UUID."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillType":{"type":["string","null"],"description":"hard, soft or language."},"title":{"type":"string"}},"required":["id","level","title"]}},"translations":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"description":"On families/clusters this is the main descriptive text ('structured' is always null there). On roles/levels it is only an internal working summary: machine-translated languages leave it blank ? blank is normal, not missing content ? and the profile content users see lives in 'structured' (which may itself contain a section named 'Description')."},"language":{"type":"string","description":"BCP-47 tag (e.g. 'en-US')."},"structured":{"description":"Content sections (e.g. responsibilities, qualifications); TASKS sections are excluded, see 'tasks'. Pass verbatim back to 'update_job_role' / 'update_job_level' on a partial edit to preserve them.","type":["array","null"],"items":{"$ref":"#/$defs/McpJobProfileContentElementInput"}},"title":{"type":"string"}},"required":["language","title"]}},"version":{"type":"integer","format":"int32","description":"Monotonically increasing, starting at 1."}},"required":["englishTitle","itemId","jobArchitectureId","layer","skills","translations","version"],"description":"Null = unknown architecture, item or version."}}} -
get_job_profile_templateFetch the job profile template assigned to a job architecture. The 'template' field is null when no template has been assigned yet ? in that case the agent must stop and surface this to the user instead of authoring profile content. When present, returns the ordered role and level sections (section id, English name, guidance, content format type, min/max item counts) and the per-scope skill detection limits. Use this to understand the required structure and content rules when authoring or updating a role/level job profile translation.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."}},"required":["jobArchitectureId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpJobProfileTemplateSection":{"type":"object","properties":{"contentType":{"type":"string","description":"BULLET_POINTS, SENTENCES or TASKS. Never author structured text for TASKS sections."},"guidance":{"type":"string","description":"Follow when authoring this section."},"maxNumberOfItems":{"type":"integer","format":"int32"},"minNumberOfItems":{"type":"integer","format":"int32"},"name":{"type":"string","description":"English name (e.g. 'Responsibilities')."},"names":{"description":"Localized display names.","type":"array","items":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 tag."},"text":{"type":"string"}},"required":["language","text"]}},"origin":{"type":"string","description":"e.g. SYSTEM, CUSTOM."},"sectionId":{"type":"string","description":"Use as the structured element 'id' when authoring this section."}},"required":["contentType","guidance","maxNumberOfItems","minNumberOfItems","name","origin","sectionId"]},"McpSkillLimits":{"type":"object","properties":{"expectedNumberOfSkills":{"type":"integer","format":"int32","description":"Target skill count ? aim for this when detecting skills."},"maximumNumberOfSkills":{"type":"integer","format":"int32","description":"Hard cap."},"skillDetectionPreference":{"type":["string","null"],"description":"Free-text soft preference biasing skill detection (max 5000 chars)."}},"required":["expectedNumberOfSkills","maximumNumberOfSkills"]}},"type":"object","properties":{"template":{"type":["object","null"],"properties":{"description":{"type":"string"},"jobLevelSections":{"description":"Sections to author for a job level.","type":"array","items":{"$ref":"#/$defs/McpJobProfileTemplateSection"}},"jobRoleSections":{"description":"Sections to author for a job role.","type":"array","items":{"$ref":"#/$defs/McpJobProfileTemplateSection"}},"levelSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"name":{"type":"string"},"roleSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"templateId":{"type":"string"}},"required":["description","jobLevelSections","jobRoleSections","levelSkillLimits","name","roleSkillLimits","templateId"],"description":"Null = no template assigned yet ? surface this to the user and do not author profile content until one is configured."}}} -
get_jsa_overviewReturn the FULL structural tree of a job architecture in one call: every family, its clusters, each cluster's roles and each role's levels ? titles (incl. localized titles per tenant language), ids and rollup counts only, no descriptions/skills/structured content, plus architecture-wide totals, the architecture's own title (incl. localized titles) and, when captured at creation, the company context ('companyContext': company name, description, future priorities, size, business units, primary goals). Role and level titles reflect each item's current (published-or-latest) version, matching 'get_nodes'. Call this FIRST to orient. The result is large and offloaded: navigate it with jq/grep to locate any node by name (in any tenant language) or by count ? there is no separate family/cluster/role search. For a node's full content call 'get_nodes'. 'availableLanguages' lists the BCP-47 tags you can request from 'get_nodes' to fetch content in a chosen language.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."}},"required":["jobArchitectureId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"Map_String.String_":{"type":"object"}},"type":"object","properties":{"availableLanguages":{"description":"BCP-47 tags used in this architecture. Pass the user's language to 'get_nodes' via 'languages'; English is always returned.","type":"array","items":{"type":"string"}},"clustersCount":{"type":"integer","format":"int32"},"companyContext":{"type":["object","null"],"properties":{"businessUnits":{"description":"Business units the architecture covers.","type":"array","items":{"type":"string"}},"companyDescription":{"type":["string","null"],"description":"What the company does."},"companyName":{"type":["string","null"],"description":"Name of the company the architecture was built for."},"companyPriorities":{"type":["string","null"],"description":"The company's strategic/future priorities."},"companySize":{"type":"integer","format":"int32","description":"Approximate employee count."},"primaryGoalOtherText":{"type":["string","null"],"description":"Free-text goal when 'primaryGoals' contains 'other'."},"primaryGoals":{"description":"Primary goals driving the architecture: 'eu_pay_transparency', 'reorganization', 'sap_success_factors' or 'other'.","type":"array","items":{"type":"string"}}},"required":["companySize"],"description":"Company context captured when the architecture was created: what the company does, its future priorities, size, business units and primary goals. Null when never provided."},"families":{"description":"Full tree: families with clusters, clusters with roles, roles with levels. Metadata only, including titles, ids, localized titles, external ids and counts ? fetch node content via 'get_nodes'.","type":"array","items":{"type":"object","properties":{"clusterCount":{"type":"integer","format":"int32"},"clusters":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":["string","null"],"description":"Customer-supplied external id."},"id":{"type":"string"},"levelsCount":{"type":"integer","format":"int32","description":"Rollup, includes nested."},"localizedTitles":{"$ref":"#/$defs/Map_String.String_","description":"Localized titles differing from 'title', by BCP-47 tag."},"roles":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":["string","null"],"description":"Customer-supplied external id."},"id":{"type":"string"},"levels":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":["string","null"],"description":"Customer-supplied external id."},"id":{"type":"string"},"localizedTitles":{"$ref":"#/$defs/Map_String.String_","description":"Localized titles differing from 'title', by BCP-47 tag."},"reviewerUserId":{"type":["string","null"],"description":"User UUID of the assigned reviewer; null when none."},"title":{"type":"string","description":"English title."}},"required":["id","localizedTitles","title"]}},"levelsCount":{"type":"integer","format":"int32"},"localizedTitles":{"$ref":"#/$defs/Map_String.String_","description":"Localized titles differing from 'title', by BCP-47 tag."},"reviewerUserId":{"type":["string","null"],"description":"User UUID of the assigned reviewer; null when none."},"title":{"type":"string","description":"English title."}},"required":["id","levels","levelsCount","localizedTitles","title"]}},"rolesCount":{"type":"integer","format":"int32","description":"Rollup, includes nested."},"title":{"type":"string","description":"English title."}},"required":["id","levelsCount","localizedTitles","roles","rolesCount","title"]}},"externalId":{"type":["string","null"],"description":"Customer-supplied external id."},"id":{"type":"string"},"levelsCount":{"type":"integer","format":"int32","description":"Rollup, includes nested."},"localizedTitles":{"$ref":"#/$defs/Map_String.String_","description":"Localized titles differing from 'title', by BCP-47 tag."},"rolesCount":{"type":"integer","format":"int32","description":"Rollup, includes nested."},"title":{"type":"string","description":"English title."}},"required":["clusterCount","clusters","id","levelsCount","localizedTitles","rolesCount","title"]}},"familiesCount":{"type":"integer","format":"int32"},"jobArchitectureId":{"type":"string"},"levelsCount":{"type":"integer","format":"int32"},"localizedTitles":{"$ref":"#/$defs/Map_String.String_","description":"Localized titles differing from 'title', by BCP-47 tag."},"rolesCount":{"type":"integer","format":"int32"},"title":{"type":"string","description":"English title of the job architecture."}},"required":["clustersCount","families","familiesCount","jobArchitectureId","levelsCount","rolesCount"]} -
get_level_pay_contextResolve the leveling-framework level a job level is pinned to, and return that level's pay. Saves joining the level's selected career track against 'get_leveling_framework' by hand. Returns configured=false when the job level is not pinned to a framework level. English text only on output.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"levelId":{"type":"string","description":"Job level UUID."}},"required":["levelId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"configured":{"type":"boolean","description":"False = this job level is not pinned to a leveling-framework level; every other field is then null."},"currency":{"type":["string","null"],"description":"ISO 4217 currency of the framework; regional bands may override it."},"frameworkId":{"type":["string","null"]},"frameworkName":{"type":["string","null"]},"level":{"type":["object","null"],"properties":{"compensation":{"description":"The level's pay. The entry without a 'region' is the level's default pay; any further entries are regional bands. Empty when no pay has been set.","type":"array","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217. A band may use a different currency from the framework's."},"fringeBenefits":{"type":["string","null"]},"longTermIncentive":{"type":["string","null"]},"name":{"type":["string","null"],"description":"Label for the band, e.g. \"Denmark\". Absent on the level's default pay."},"payType":{"type":["string","null"],"description":"SALARIED or HOURLY."},"region":{"type":["string","null"],"description":"Country or region this band applies to. Absent on the level's default pay."},"salaryMaximum":{"type":["number","null"]},"salaryMidpoint":{"type":["number","null"]},"salaryMinimum":{"type":["number","null"]},"targetBonus":{"type":["string","null"]}}}},"description":{"type":"string"},"employmentType":{"type":["string","null"],"description":"TARIF or AT. Applies to the whole level."},"level":{"type":"integer","format":"int32","description":"1-based within the track."},"name":{"type":"string"},"payGrade":{"type":["string","null"],"description":"Applies to the whole level, every pay band included."},"progressionCriteria":{"type":["string","null"]}},"required":["description","level","name"],"description":"The framework level itself, including its default pay and every regional band."},"levelId":{"type":"string","description":"The job level this pay context was resolved for ? not the framework level below."},"trackId":{"type":["string","null"]},"trackName":{"type":["string","null"]}},"required":["configured","levelId"]} -
get_leveling_frameworkFetch a leveling framework by id. When 'jobArchitectureId' is given the lookup is restricted to that architecture's scoped frameworks; otherwise the tenant- or globally-scoped framework is returned. English text only on output. Throws when no matching framework exists.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"frameworkId":{"type":"string","description":"Leveling framework UUID."},"jobArchitectureId":{"type":"string","description":"Optional job architecture UUID to scope the lookup to."}},"required":["frameworkId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"currency":{"type":["string","null"],"description":"ISO 4217, for salary data on the framework's levels."},"description":{"type":"string"},"frameworkId":{"type":"string"},"jobArchitectureId":{"type":["string","null"],"description":"Null for tenant- or globally-scoped frameworks."},"lastUpdate":{"type":"string","format":"date-time"},"name":{"type":"string"},"ownerScope":{"type":"string","description":"GLOBAL (system-wide) or TENANT (owned by the caller's tenant)."},"tracks":{"description":"Career tracks (lanes), in defined ordering.","type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"levels":{"description":"Ordered by ascending level number.","type":"array","items":{"type":"object","properties":{"compensation":{"description":"The level's pay. The entry without a 'region' is the level's default pay; any further entries are regional bands. Empty when no pay has been set.","type":"array","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217. A band may use a different currency from the framework's."},"fringeBenefits":{"type":["string","null"]},"longTermIncentive":{"type":["string","null"]},"name":{"type":["string","null"],"description":"Label for the band, e.g. \"Denmark\". Absent on the level's default pay."},"payType":{"type":["string","null"],"description":"SALARIED or HOURLY."},"region":{"type":["string","null"],"description":"Country or region this band applies to. Absent on the level's default pay."},"salaryMaximum":{"type":["number","null"]},"salaryMidpoint":{"type":["number","null"]},"salaryMinimum":{"type":["number","null"]},"targetBonus":{"type":["string","null"]}}}},"description":{"type":"string"},"employmentType":{"type":["string","null"],"description":"TARIF or AT. Applies to the whole level."},"level":{"type":"integer","format":"int32","description":"1-based within the track."},"name":{"type":"string"},"payGrade":{"type":["string","null"],"description":"Applies to the whole level, every pay band included."},"progressionCriteria":{"type":["string","null"]}},"required":["description","level","name"]}},"name":{"type":"string"},"trackId":{"type":"string"}},"required":["description","levels","name","trackId"]}},"type":{"type":"string","description":"MARKET, UNION or CUSTOM."}},"required":["createdAt","description","frameworkId","lastUpdate","name","ownerScope","tracks","type"]} -
get_next_actionsGet ranked next work for the current user plus compact job-architecture progress. Use for questions such as 'what shall I do next?' or 'what remains?'.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Optional job architecture UUID to scope recommendations."}},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpNextAction":{"type":"object","properties":{"code":{"type":"string"},"priority":{"type":"integer","format":"int32"},"reason":{"type":"object","properties":{"actual":{"type":["integer","null"],"format":"int32"},"code":{"type":"string"},"required":{"type":["integer","null"],"format":"int32"}},"required":["code"]},"requiredCapability":{"type":["string","null"]},"source":{"type":"string"},"status":{"type":"string"},"target":{"type":"object","properties":{"itemId":{"type":["string","null"]},"jobArchitectureId":{"type":"string"},"kind":{"type":"string"},"notificationIds":{"type":"array","items":{"type":"string"}},"versionNo":{"type":["integer","null"],"format":"int32"}},"required":["jobArchitectureId","kind"]}},"required":["code","priority","reason","source","status","target"]}},"type":"object","properties":{"alternativeActions":{"type":"array","items":{"$ref":"#/$defs/McpNextAction"}},"architectureProgress":{"type":"array","items":{"type":"object","properties":{"jobArchitectureId":{"type":"string"},"publicationCompleted":{"type":"integer","format":"int32"},"publicationTotal":{"type":"integer","format":"int32"},"setupCompleted":{"type":"integer","format":"int32"},"setupTotal":{"type":"integer","format":"int32"},"title":{"type":"string"}},"required":["jobArchitectureId","publicationCompleted","publicationTotal","setupCompleted","setupTotal","title"]}},"outcome":{"type":"string"},"primaryAction":{"anyOf":[{"type":"null"},{"$ref":"#/$defs/McpNextAction"}]}},"required":["alternativeActions","architectureProgress","outcome"]} -
get_nodesFetch full detail for up to 25 listed nodes at once, mixing families, clusters, roles and levels, or for every node of the given types below given parents via 'scope' (up to 200, e.g. all roles of the architecture or of one family) ? use 'scope' instead of listing ids whenever you need many nodes. Families and clusters return title, description, parent, counts and translations (localized titles for every tenant language); roles and levels return full localized detail (title, description and structured content per tenant language under 'translations'. The structured content contains an identifier, which can be resolved to a localized name via the sectionTags. The value is either a newline separated string (sentences format) or a <ul><li> separated html string (bullet point format)) plus the current version number, the attached skills (each with its required proficiency level and an optional competency grouping) and the competency definitions those groupings reference. Each node may carry an optional 'version' that selects a past version of a role or level (ignored for families and clusters); The same role or level id may be listed more than once with different 'version' values to fetch several versions in one call. Ids that do not resolve or belong to a different architecture are returned in 'notFound'. Use after locating ids via 'get_jsa_overview'. By default every tenant language is returned; pass 'languages' to restrict the localized content to the language(s) you need.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID all nodes must belong to."},"nodes":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string","description":"Family, cluster, role or level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"Role/level only: return this past version's content instead of the current state. Omit for current. List versions via 'list_job_architecture_versions'."}},"required":["nodeId"]},"description":"Nodes to fetch (max 25), each an object with 'nodeId' and an optional 'version'. May mix families, clusters, roles and levels. 'version' is applied only to roles/levels; repeat a role/level id with different versions to fetch several at once."},"languages":{"type":"array","items":{"type":"string"},"description":"Optional BCP-47 language tags to return localized content in (e.g. ['de-DE'] or ['fr-FR']). Pass the language the user is writing in to avoid shipping every language's structured content; English is always included as the canonical base. Available tags are listed in 'get_jsa_overview.availableLanguages'. Omit to return all languages."},"scope":{"type":"object","properties":{"parentIds":{"description":"Architecture, family, cluster or role UUIDs whose descendants to return. Pass the job architecture id for the whole architecture.","type":"array","items":{"type":"string"}},"types":{"description":"Node types to return from below those parents.","type":"array","items":{"type":"string","enum":["FAMILY","CLUSTER","ROLE","LEVEL"]}}},"required":["parentIds","types"],"description":"Fetch every current node of 'types' below 'parentIds' (max 200 matches). Combined with 'nodes' when both are given. Parents outside this architecture are returned in 'notFound'."}},"required":["jobArchitectureId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpAttachedSkill":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Matches an entry in 'competencies'. Null = ungrouped."},"id":{"type":"string","description":"Skill UUID in the skill graph."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillType":{"type":["string","null"],"description":"hard, soft or language."},"title":{"type":"string","description":"In the snapshot's language."}},"required":["id","level","title"]},"McpCompetency":{"type":"object","properties":{"competencyId":{"type":"string","description":"Referenced by the grouped skills' 'competencyId'."},"description":{"type":["string","null"]},"title":{"type":"string","description":"Falls back to English when untranslated."}},"required":["competencyId","title"]},"McpSectionTag":{"type":"object","properties":{"names":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 tag."},"text":{"type":"string"}},"required":["language","text"]}},"sectionId":{"type":"string","description":"Matches the 'id' of structured content elements in this section."},"type":{"type":"string","description":"Content format: BULLET_POINTS, SENTENCES or TASKS. TASKS content lives in 'tasks'; never author structured text for it."}},"required":["names","sectionId"]},"McpTranslation":{"type":"object","properties":{"description":{"type":["string","null"],"description":"On families/clusters this is the main descriptive text ('structured' is always null there). On roles/levels it is only an internal working summary: machine-translated languages leave it blank ? blank is normal, not missing content ? and the profile content users see lives in 'structured' (which may itself contain a section named 'Description')."},"language":{"type":"string","description":"BCP-47 tag (e.g. 'en-US')."},"structured":{"description":"Content sections (e.g. responsibilities, qualifications); TASKS sections are excluded, see 'tasks'. Pass verbatim back to 'update_job_role' / 'update_job_level' on a partial edit to preserve them.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string"}},"required":["language","title"]},"McpWorkTask":{"type":"object","properties":{"description":{"type":["string","null"]},"generationState":{"type":"string","description":"QUEUED, STARTED, FINISHED or FAILED. Only FINISHED tasks accept 'update_work_task'."},"order":{"type":"integer","format":"int32","description":"Position in the TASKS section, ascending from 0."},"requiredSkills":{"type":"array","items":{"type":"object","properties":{"level":{"type":"integer","description":"Proficiency 0..6."},"skillId":{"type":"string"}},"required":["level","skillId"]}},"taskId":{"type":"string"},"title":{"type":"string","description":"Empty until generation produced one."},"version":{"type":"integer","format":"int32","description":"Immutable task version pinned to this role/level version."}},"required":["generationState","order","taskId","title","version"]}},"type":"object","properties":{"clusters":{"type":"array","items":{"type":"object","properties":{"clusterId":{"type":"string"},"englishDescription":{"type":["string","null"],"description":"The cluster's primary user-facing text ? unlike on roles/levels, this is real content."},"englishTitle":{"type":"string","description":"Empty when no English translation exists."},"externalId":{"type":["string","null"],"description":"Customer-supplied external id."},"familyId":{"type":"string","description":"Parent family UUID."},"jobArchitectureId":{"type":"string"},"levelsCount":{"type":"integer","format":"int32","description":"Rollup, includes nested."},"rolesCount":{"type":"integer","format":"int32","description":"Rollup, includes nested."},"translations":{"description":"Title + description per language; no structured content. 'description' here is the primary user-facing text.","type":"array","items":{"$ref":"#/$defs/McpTranslation"}}},"required":["clusterId","englishTitle","familyId","jobArchitectureId","levelsCount","rolesCount","translations"]}},"families":{"type":"array","items":{"type":"object","properties":{"clusterCount":{"type":"integer","format":"int32"},"englishDescription":{"type":["string","null"],"description":"The family's primary user-facing text ? unlike on roles/levels, this is real content."},"englishTitle":{"type":"string","description":"Empty when no English translation exists."},"externalId":{"type":["string","null"],"description":"Customer-supplied external id."},"familyId":{"type":"string"},"jobArchitectureId":{"type":"string"},"levelsCount":{"type":"integer","format":"int32","description":"Rollup, includes nested."},"rolesCount":{"type":"integer","format":"int32","description":"Rollup, includes nested."},"translations":{"description":"Title + description per language; no structured content. 'description' here is the primary user-facing text.","type":"array","items":{"$ref":"#/$defs/McpTranslation"}}},"required":["clusterCount","englishTitle","familyId","jobArchitectureId","levelsCount","rolesCount","translations"]}},"levels":{"type":"array","items":{"type":"object","properties":{"canAssignReviewer":{"type":["boolean","null"],"description":"False = do not propose a reviewer change."},"competencies":{"description":"Referenced by the skills' 'competencyId'.","type":"array","items":{"$ref":"#/$defs/McpCompetency"}},"currentVersion":{"type":["integer","null"],"format":"int32","description":"Version this content reflects; null before any version exists. Past version: 'version' arg of 'get_nodes'; list via 'list_job_architecture_versions'."},"isArchived":{"type":"boolean","description":"Archived = hidden but recoverable."},"jobArchitectureId":{"type":"string"},"jobProfileId":{"type":["string","null"],"description":"Current job profile UUID. Null = none exists yet."},"levelId":{"type":"string"},"reviewerUserId":{"type":["string","null"]},"roleId":{"type":"string","description":"Parent role UUID."},"sectionTags":{"description":"Resolves a structured element's 'id' to localized section names. Null = no job profile.","type":["array","null"],"items":{"$ref":"#/$defs/McpSectionTag"}},"skills":{"type":"array","items":{"$ref":"#/$defs/McpAttachedSkill"}},"tasks":{"description":"Work tasks of the TASKS section, in order. Null = no TASKS section; empty = section without tasks. Edit only via the '*_work_task' tools, never through 'structured'.","type":["array","null"],"items":{"$ref":"#/$defs/McpWorkTask"}},"translations":{"description":"One entry per tenant language. On a partial edit, pass the matching entry's 'description' and 'structured' verbatim to 'update_job_level' to preserve existing values.","type":"array","items":{"$ref":"#/$defs/McpTranslation"}}},"required":["isArchived","jobArchitectureId","levelId","roleId","translations"]}},"notFound":{"description":"Requested ids that did not resolve or belong to another architecture.","type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"type":"object","properties":{"canAssignReviewer":{"type":["boolean","null"],"description":"False = do not propose a reviewer change."},"clusterId":{"type":"string","description":"Parent cluster UUID."},"competencies":{"description":"Referenced by the skills' 'competencyId'.","type":"array","items":{"$ref":"#/$defs/McpCompetency"}},"currentVersion":{"type":["integer","null"],"format":"int32","description":"Version this content reflects; null before any version exists. Past version: 'version' arg of 'get_nodes'; list via 'list_job_architecture_versions'."},"isArchived":{"type":"boolean","description":"Archived = hidden but recoverable."},"jobArchitectureId":{"type":"string"},"jobProfileId":{"type":["string","null"],"description":"Current job profile UUID. Null = none exists yet."},"reviewerUserId":{"type":["string","null"]},"roleId":{"type":"string"},"sectionTags":{"description":"Resolves a structured element's 'id' to localized section names. Null = no job profile.","type":["array","null"],"items":{"$ref":"#/$defs/McpSectionTag"}},"skills":{"type":"array","items":{"$ref":"#/$defs/McpAttachedSkill"}},"tasks":{"description":"Work tasks of the TASKS section, in order. Null = no TASKS section; empty = section without tasks. Edit only via the '*_work_task' tools, never through 'structured'.","type":["array","null"],"items":{"$ref":"#/$defs/McpWorkTask"}},"translations":{"description":"One entry per tenant language. On a partial edit, pass the matching entry's 'description' and 'structured' verbatim to 'update_job_role' to preserve existing values.","type":"array","items":{"$ref":"#/$defs/McpTranslation"}}},"required":["clusterId","isArchived","jobArchitectureId","roleId","translations"]}}},"required":["clusters","families","levels","notFound","roles"]} -
get_skillFetch a single skill by id. Returns the English title, type (hard/soft/language), English description, and the proficiency-level rubric (per level: short and long description plus sub-skills). Use after 'search_skills' or 'semantic_search_skills' to understand a skill before referencing its id in skillEdits. Returns {skill: null} when the id is unknown.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"skillId":{"type":"string","description":"Skill UUID."}},"required":["skillId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"skill":{"type":["object","null"],"properties":{"description":{"type":["string","null"]},"proficiencyLevels":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"]},"level":{"type":"integer","format":"int32","description":"Level number (e.g. 1..5)."},"shortDescription":{"type":["string","null"]},"subSkills":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"]},"title":{"type":"string"}},"required":["title"]}}},"required":["level"]}},"skillId":{"type":"string","description":"Use verbatim in surgical skillEdits. Inventing ids is forbidden."},"skillType":{"type":"string","description":"'hard' (technical), 'soft' (behavioural) or 'language'."},"title":{"type":"string","description":"Canonical English title."}},"required":["skillId","skillType","title"],"description":"Null = unknown skill id."}}} -
get_work_task_commentsList work-task comment threads for a version. Returns open, non-stale roots and their replies by default; optional filters include resolved or stale threads or select one source language.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID the role/level belongs to."},"itemId":{"type":"string","description":"Role or level UUID the task belongs to."},"taskId":{"type":"string","description":"Work task UUID."},"language":{"type":"string","description":"BCP-47 source-language tag. Omit for all languages."},"includeResolved":{"type":"boolean","description":"Include resolved threads. Defaults to false."},"version":{"type":"integer","format":"int32","description":"Task version. Omit for the version currently pinned to the item."},"includeStale":{"type":"boolean","description":"Include comments whose anchor is stale. Defaults to false."}},"required":["jobArchitectureId","itemId","taskId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"comments":{"description":"Flattened: a reply carries the 'parentCommentId' of the comment it answers.","type":"array","items":{"type":"object","properties":{"anchorStatus":{"type":["string","null"],"description":"Vs current content: 'anchored' (highlighted text still exists), 'unresolved' (not found) or 'ambiguous' (matches more than one place). Treat 'unresolved'/'ambiguous' as stale ? do not act on them unless the user explicitly refers to them. Null for 'title'/'skill' comments."},"authorId":{"type":["string","null"]},"authorName":{"type":["string","null"]},"commentId":{"type":"string"},"content":{"type":"string"},"language":{"type":"string","description":"BCP-47 tag."},"parentCommentId":{"type":["string","null"],"description":"Null = top-level comment."},"quotedText":{"type":["string","null"],"description":"Text the user highlighted ? what the feedback is about."},"resolved":{"type":"boolean"},"resolvedInVersion":{"type":["integer","null"],"format":"int32","description":"Version that resolved the thread. Null = open."},"sectionId":{"type":["string","null"],"description":"Only for 'description-section'."},"skillId":{"type":["string","null"],"description":"Only for 'skill'."},"stepIndex":{"type":["integer","null"],"format":"int32","description":"Only for work-task workflow-step targets."},"targetKind":{"type":"string","description":"Profile or work-task target kind."},"version":{"type":["integer","null"],"format":"int32","description":"Content version the comment targets."}},"required":["commentId","content","language","resolved","targetKind"]}}}} -
list_archived_itemsList every ARCHIVED job role and job level of a job architecture. Archived items are invisible to 'get_jsa_overview', 'get_nodes' and the search tools, so this is the only way to discover them or resolve an archived item's title to its id ('resolve_entities' maps known archived ids to their ancestors but carries no titles). Returns ids, titles (incl. localized titles) and ancestor ids plus each level's parent role id. A level's parent role may itself be archived ? it then also appears in 'roles' and is restored automatically when the level is unarchived.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."}},"required":["jobArchitectureId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpArchivedItemView":{"type":"object","properties":{"archivedAt":{"type":["string","null"],"format":"date-time"},"clusterId":{"type":["string","null"],"description":"Ancestor cluster."},"familyId":{"type":["string","null"],"description":"Ancestor family."},"id":{"type":"string"},"localizedTitles":{"type":"object","description":"Localized titles differing from 'title', by BCP-47 tag."},"parentRoleId":{"type":["string","null"],"description":"Levels only: UUID of the parent role. The role may itself be archived ? it then also appears in 'roles'."},"title":{"type":"string","description":"English title."}},"required":["id","localizedTitles","title"]}},"type":"object","properties":{"jobArchitectureId":{"type":"string"},"levels":{"type":"array","items":{"$ref":"#/$defs/McpArchivedItemView"}},"roles":{"type":"array","items":{"$ref":"#/$defs/McpArchivedItemView"}}},"required":["jobArchitectureId","levels","roles"]} -
list_cobrainer_job_profile_templatesList all Cobrainer-managed (system) job profile templates across statuses (DRAFT, ACTIVE, DEPRECATED). These are distinct from per-job-architecture custom templates returned by 'get_job_profile_template'. English text only on output.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpCobrainerTemplateSectionView":{"type":"object","properties":{"contentType":{"type":"string","description":"BULLET_POINTS, SENTENCES or TASKS."},"guidance":{"type":"string","description":"Follow when authoring this section."},"maxNumberOfItems":{"type":"integer","format":"int32"},"minNumberOfItems":{"type":"integer","format":"int32"},"name":{"type":"string"},"sectionId":{"type":"string","description":"Use as the 'tag' when authoring structured content."}},"required":["contentType","guidance","maxNumberOfItems","minNumberOfItems","name","sectionId"]},"McpSkillLimits":{"type":"object","properties":{"expectedNumberOfSkills":{"type":"integer","format":"int32","description":"Target skill count ? aim for this when detecting skills."},"maximumNumberOfSkills":{"type":"integer","format":"int32","description":"Hard cap."},"skillDetectionPreference":{"type":["string","null"],"description":"Free-text soft preference biasing skill detection (max 5000 chars)."}},"required":["expectedNumberOfSkills","maximumNumberOfSkills"]}},"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"activatedAt":{"type":["string","null"],"format":"date-time","description":"Null = never activated."},"createdAt":{"type":"string","format":"date-time"},"description":{"type":"string"},"jobLevelSections":{"type":"array","items":{"$ref":"#/$defs/McpCobrainerTemplateSectionView"}},"jobRoleSections":{"type":"array","items":{"$ref":"#/$defs/McpCobrainerTemplateSectionView"}},"levelSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"name":{"type":"string"},"roleSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"status":{"type":"string","description":"DRAFT, ACTIVE or DEPRECATED."},"templateId":{"type":"string"}},"required":["createdAt","description","jobLevelSections","jobRoleSections","levelSkillLimits","name","roleSkillLimits","status","templateId"]}}},"required":["items"]} -
list_job_architecture_change_eventsFetch a page of change-log events for a job architecture in reverse-chronological order. Each event includes actor, entity, event type (CREATED, EDITED, SKILLS_UPDATED, REVIEWED, PUBLISHED, ARCHIVED, ...), field-level old/new values where applicable, and the affected version. SKILLS_UPDATED events carry the exact required-skill diff (skillsAdded, skillsRemoved, skillsLevelChanged with old/new proficiency). Task events (TASK_CREATED, TASK_EDITED, TASK_DELETED, TASKS_REORDERED, TASK_SKILLS_UPDATED) are anchored on the role/level whose profile carries the task and name the task in 'task' or 'tasks'. Useful to answer 'what changed recently?', 'when did skills change?', or audit a specific role/level via its change history.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"page":{"type":"integer","format":"int32","description":"0-based page number. Defaults to 0."},"size":{"type":"integer","format":"int32","description":"Page size (max 200). Defaults to 20."}},"required":["jobArchitectureId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpChangeLogEntityView":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Name at the time of the event."},"type":{"type":["string","null"],"description":"'root', 'family', 'cluster', 'role' or 'level'."}},"required":["id","name"]},"McpChangeLogEntityView-nullable":{"anyOf":[{"type":"null"},{"$ref":"#/$defs/McpChangeLogEntityView"}]},"McpChangedSkill":{"type":"object","properties":{"id":{"type":"string"},"level":{"type":["integer","null"],"format":"int32"},"title":{"type":"string"}},"required":["id","title"]},"McpChangedTask":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"version":{"type":"integer","format":"int32","description":"Task version the event left the item pinned to."}},"required":["id","title","version"]}},"type":"object","properties":{"events":{"description":"Newest first.","type":"array","items":{"type":"object","properties":{"actorName":{"type":["string","null"]},"actorUserId":{"type":["string","null"],"description":"Null for system-driven changes."},"changeId":{"type":"string","description":"Logical change id; multiple events can share it."},"entity":{"$ref":"#/$defs/McpChangeLogEntityView"},"entityType":{"type":"string","description":"'root', 'family', 'cluster', 'role' or 'level'."},"eventId":{"type":"string"},"eventType":{"type":"string","description":"e.g. CREATED, UPDATED, PUBLISHED."},"field":{"type":["string","null"],"description":"Changed field, for field-level edits."},"from":{"$ref":"#/$defs/McpChangeLogEntityView-nullable","description":"Previous location; only for move events."},"itemId":{"type":["string","null"],"description":"Null for architecture-wide events."},"language":{"type":["string","null"],"description":"BCP-47 tag; only for translation events."},"newValue":{"type":["string","null"]},"oldValue":{"type":["string","null"]},"onBehalfOfUser":{"type":"boolean","description":"True = the actor acted on behalf of another user."},"parent":{"$ref":"#/$defs/McpChangeLogEntityView-nullable","description":"Parent context (e.g. the cluster of a role). Null when not applicable."},"publisherUserId":{"type":["string","null"],"description":"Only for publish/unpublish events."},"reviewerUserId":{"type":["string","null"],"description":"Only for reviewer assignment/review events."},"skillsAdded":{"description":"Required skills added; only for SKILLS_UPDATED and TASK_SKILLS_UPDATED events.","type":["array","null"],"items":{"$ref":"#/$defs/McpChangedSkill"}},"skillsLevelChanged":{"description":"Required-proficiency changes; only for SKILLS_UPDATED and TASK_SKILLS_UPDATED events.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":"string"},"newLevel":{"type":"integer","format":"int32"},"oldLevel":{"type":"integer","format":"int32"},"title":{"type":"string"}},"required":["id","newLevel","oldLevel","title"]}},"skillsRemoved":{"description":"Required skills removed; only for SKILLS_UPDATED and TASK_SKILLS_UPDATED events.","type":["array","null"],"items":{"$ref":"#/$defs/McpChangedSkill"}},"task":{"anyOf":[{"type":"null"},{"$ref":"#/$defs/McpChangedTask"}],"description":"Only for TASK_CREATED, TASK_EDITED, TASK_DELETED and TASK_SKILLS_UPDATED events."},"tasks":{"description":"New order; only for TASKS_REORDERED events.","type":["array","null"],"items":{"$ref":"#/$defs/McpChangedTask"}},"timestamp":{"type":"string","format":"date-time"},"to":{"$ref":"#/$defs/McpChangeLogEntityView-nullable","description":"New location; only for move events."},"version":{"type":["integer","null"],"format":"int32","description":"Affected item version; for reviewer, review, publish, skill, version and task events."}},"required":["changeId","entity","entityType","eventId","eventType","onBehalfOfUser","timestamp"]}},"page":{"type":"integer","format":"int32","description":"Zero-based."},"size":{"type":"integer","format":"int32"},"totalEvents":{"type":"integer","format":"int32","description":"Across all pages."},"totalPages":{"type":"integer","format":"int32"}},"required":["events","page","size","totalEvents","totalPages"]} -
list_job_architecture_versionsList all versions of a job role or job level in descending order.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."}},"required":["jobArchitectureId","itemId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpJobProfileContentElementInput":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"comment":{"type":["string","null"]},"competencies":{"description":"Referenced by the skills' 'competencyId'.","type":"array","items":{"type":"object","properties":{"competencyId":{"type":"string","description":"Referenced by the grouped skills' 'competencyId'."},"description":{"type":["string","null"]},"title":{"type":"string","description":"Falls back to English when untranslated."}},"required":["competencyId","title"]}},"englishDescription":{"type":["string","null"],"description":"Internal working summary, not part of the rendered profile. Often blank ? blank is normal, not missing content. The profile content users see lives in 'englishStructured'."},"englishStructured":{"description":"English content sections. Pass verbatim back to 'update_job_role' / 'update_job_level' on a partial edit to preserve them.","type":["array","null"],"items":{"$ref":"#/$defs/McpJobProfileContentElementInput"}},"englishTitle":{"type":"string","description":"Empty when no English translation exists."},"itemId":{"type":"string","description":"Role or level UUID."},"jobArchitectureId":{"type":"string"},"layer":{"type":"string","description":"'ROLE' or 'LEVEL'."},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Null = still draft."},"reviewedAt":{"type":["string","null"],"format":"date-time","description":"Null = unreviewed."},"sectionTags":{"type":["array","null"],"items":{"type":"object","properties":{"names":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 tag."},"text":{"type":"string"}},"required":["language","text"]}},"sectionId":{"type":"string","description":"Matches the 'id' of structured content elements in this section."},"type":{"type":"string","description":"Content format: BULLET_POINTS, SENTENCES or TASKS. TASKS content lives in 'tasks'; never author structured text for it."}},"required":["names","sectionId"]}},"skills":{"type":"array","items":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Matches an entry in 'competencies'. Null = ungrouped."},"id":{"type":"string","description":"Skill UUID."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillType":{"type":["string","null"],"description":"hard, soft or language."},"title":{"type":"string"}},"required":["id","level","title"]}},"translations":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"description":"On families/clusters this is the main descriptive text ('structured' is always null there). On roles/levels it is only an internal working summary: machine-translated languages leave it blank ? blank is normal, not missing content ? and the profile content users see lives in 'structured' (which may itself contain a section named 'Description')."},"language":{"type":"string","description":"BCP-47 tag (e.g. 'en-US')."},"structured":{"description":"Content sections (e.g. responsibilities, qualifications); TASKS sections are excluded, see 'tasks'. Pass verbatim back to 'update_job_role' / 'update_job_level' on a partial edit to preserve them.","type":["array","null"],"items":{"$ref":"#/$defs/McpJobProfileContentElementInput"}},"title":{"type":"string"}},"required":["language","title"]}},"version":{"type":"integer","format":"int32","description":"Monotonically increasing, starting at 1."}},"required":["englishTitle","itemId","jobArchitectureId","layer","skills","translations","version"]}}},"required":["items"]} -
list_leveling_frameworksList leveling frameworks visible to the caller. When 'jobArchitectureId' is omitted the result is the tenant-wide list (tenant-owned plus global frameworks). When given, only frameworks scoped to that job architecture are returned. English text only on output. Pagination is 0-based; size is capped at 200.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Optional job architecture UUID to scope results to."},"page":{"type":"integer","format":"int32","description":"0-based page number. Defaults to 0."},"size":{"type":"integer","format":"int32","description":"Page size (max 200). Defaults to 20."}},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"currency":{"type":["string","null"],"description":"ISO 4217, for salary data on the framework's levels."},"description":{"type":"string"},"frameworkId":{"type":"string"},"jobArchitectureId":{"type":["string","null"],"description":"Null for tenant- or globally-scoped frameworks."},"lastUpdate":{"type":"string","format":"date-time"},"name":{"type":"string"},"ownerScope":{"type":"string","description":"GLOBAL (system-wide) or TENANT (owned by the caller's tenant)."},"tracks":{"description":"Career tracks (lanes), in defined ordering.","type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"levels":{"description":"Ordered by ascending level number.","type":"array","items":{"type":"object","properties":{"compensation":{"description":"The level's pay. The entry without a 'region' is the level's default pay; any further entries are regional bands. Empty when no pay has been set.","type":"array","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217. A band may use a different currency from the framework's."},"fringeBenefits":{"type":["string","null"]},"longTermIncentive":{"type":["string","null"]},"name":{"type":["string","null"],"description":"Label for the band, e.g. \"Denmark\". Absent on the level's default pay."},"payType":{"type":["string","null"],"description":"SALARIED or HOURLY."},"region":{"type":["string","null"],"description":"Country or region this band applies to. Absent on the level's default pay."},"salaryMaximum":{"type":["number","null"]},"salaryMidpoint":{"type":["number","null"]},"salaryMinimum":{"type":["number","null"]},"targetBonus":{"type":["string","null"]}}}},"description":{"type":"string"},"employmentType":{"type":["string","null"],"description":"TARIF or AT. Applies to the whole level."},"level":{"type":"integer","format":"int32","description":"1-based within the track."},"name":{"type":"string"},"payGrade":{"type":["string","null"],"description":"Applies to the whole level, every pay band included."},"progressionCriteria":{"type":["string","null"]}},"required":["description","level","name"]}},"name":{"type":"string"},"trackId":{"type":"string"}},"required":["description","levels","name","trackId"]}},"type":{"type":"string","description":"MARKET, UNION or CUSTOM."}},"required":["createdAt","description","frameworkId","lastUpdate","name","ownerScope","tracks","type"]}},"page":{"type":"integer","format":"int32","description":"0-based."},"pages":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32","description":"Across all pages."}},"required":["data","page","pages","size","total"]} -
list_skill_referencesList the job-architecture ROLES and LEVELS whose profile references a given skill ? the reverse of 'get_nodes' (which lists a role/level's skills). Use it to answer 'which roles/levels require skill X?'. Provide the skill UUID; resolve a skill NAME to an id first via 'search_skills' (keyword) or 'semantic_search_skills' (conceptual). Optionally pass 'jobArchitectureId' to scope to one architecture; omit for tenant-wide. Roles and levels are returned separately, each with a 'total' count and a page of items ordered newest-first; 'page'/'size' paginate BOTH lists. Each item carries the role/level item id (feed to 'get_nodes'), its architecture id, English title and whether the reference comes from a published version. Returns empty role and level lists when the skill is unused or the id is unknown.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"skillId":{"type":"string","description":"Skill UUID. Obtain it from 'search_skills' or 'semantic_search_skills'."},"jobArchitectureId":{"type":"string","description":"Optional job architecture UUID to scope references to a single architecture. Omit for tenant-wide."},"page":{"type":"integer","format":"int32","description":"0-based page number applied to both the role and level lists. Defaults to 0."},"size":{"type":"integer","format":"int32","description":"Page size per layer (max 200). Defaults to 50."}},"required":["skillId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpSkillReferenceLayer":{"type":"object","properties":{"items":{"description":"This page, newest first.","type":"array","items":{"type":"object","properties":{"architectureId":{"type":"string"},"isFromPublishedVersion":{"type":"boolean","description":"False = only a draft references it."},"itemId":{"type":"string","description":"Role or level UUID. Pass to 'get_nodes' for full detail."},"title":{"type":"string","description":"Empty when no English profile translation exists."}},"required":["architectureId","isFromPublishedVersion","itemId","title"]}},"total":{"type":"integer","format":"int32","description":"Exceeds items.size when more pages exist."}},"required":["total"]}},"type":"object","properties":{"levels":{"$ref":"#/$defs/McpSkillReferenceLayer","description":"Levels whose profile references this skill."},"roles":{"$ref":"#/$defs/McpSkillReferenceLayer","description":"Roles whose profile references this skill."},"skillId":{"type":"string","description":"Echoes the requested skillId."},"skillType":{"type":["string","null"],"description":"'hard', 'soft' or 'language'. Null = skill id unknown."},"title":{"type":["string","null"],"description":"Canonical English title. Null = skill id unknown to the skills service."}},"required":["levels","roles","skillId"]} -
list_top_attributed_skillsRank the skills most attributed across the roles and levels of ONE job architecture ? it answers 'which skills are most attributed across THIS architecture?'. This is the complement of 'list_skill_references' (which, for a single skill, lists the roles/levels that reference it). Provide the job architecture UUID. Counts are scoped to that architecture and only count active (non-archived) roles/levels. 'attribution' selects what to rank by: ROLE counts role profiles, LEVEL counts level profiles, ROLE_LEVEL (default) ranks by their combined total. Results are ordered most-attributed first and capped to 'size' (top-N, max 200, default 50). Each skill carries its UUID, English title, skill type and the scoped role and level counts. 'totalRoleAttributions'/'totalLevelAttributions' give the architecture-wide totals across ALL skills (not just the returned top-N). Returns an empty list when the architecture has no attributed skills or the id is unknown.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID to rank skills within."},"attribution":{"type":"string","enum":["ROLE","LEVEL","ROLE_LEVEL"],"description":"What to rank by: ROLE (role profiles), LEVEL (level profiles) or ROLE_LEVEL (combined, default)."},"size":{"type":"integer","format":"int32","description":"Top-N skills to return (max 200). Defaults to 50."}},"required":["jobArchitectureId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Echoes the requested jobArchitectureId."},"skills":{"description":"Most-attributed first; capped to the requested top-N.","type":"array","items":{"type":"object","properties":{"levelCount":{"type":"integer","format":"int32","description":"Active (non-archived) level profiles referencing the skill."},"roleCount":{"type":"integer","format":"int32","description":"Active (non-archived) role profiles referencing the skill."},"skillId":{"type":"string"},"skillType":{"type":["string","null"],"description":"'hard', 'soft' or 'language'. Null = skill id unknown."},"title":{"type":["string","null"],"description":"Canonical English title. Null = skill id unknown to the skills service."}},"required":["levelCount","roleCount","skillId"]}},"totalLevelAttributions":{"type":"integer","format":"int32","description":"Sum over ALL skills' levelCount, not limited to the returned top-N."},"totalRoleAttributions":{"type":"integer","format":"int32","description":"Sum over ALL skills' roleCount, not limited to the returned top-N."}},"required":["jobArchitectureId","totalLevelAttributions","totalRoleAttributions"]} -
resolve_entitiesresolve job-architecture item UUIDs (itemIds) to their layer, ancestor ids and current version number, and skill UUIDs (skillIds) to a flat SKILL entry. Archived items resolve too, flagged 'isArchived'. Returns ids only ? for titles, descriptions or skills use 'get_nodes' (active) or 'list_archived_items' (archived) instead.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemIds":{"type":"array","items":{"type":"string"},"description":"Family/cluster/role/level UUIDs to resolve. Combined with skillIds, max 50."},"skillIds":{"type":"array","items":{"type":"string"},"description":"Skill UUIDs to resolve. Combined with itemIds, max 50."}},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entities":{"description":"One per id existing under the caller's tenant. Unknown, foreign-tenant or deleted ids are simply absent ? no error, no placeholder.","type":"array","items":{"type":"object","properties":{"clusterId":{"type":["string","null"],"description":"Ancestor cluster. Null for a family or cluster."},"entityId":{"type":"string"},"familyId":{"type":["string","null"],"description":"Ancestor family. Null for a family."},"isArchived":{"type":["boolean","null"],"description":"True when the item is archived (hidden but recoverable). Omitted for active items and skills."},"jobArchitectureId":{"type":["string","null"],"description":"Null for a skill."},"layer":{"type":"string","description":"'FAMILY', 'CLUSTER', 'ROLE', 'LEVEL' or 'SKILL'."},"roleId":{"type":["string","null"],"description":"Parent role. Only present for a level."},"skillType":{"type":["string","null"],"description":"Only for SKILL: 'hard', 'soft' or 'language'."},"version":{"type":["integer","null"],"format":"int32","description":"Current (published-or-latest) version. Null when unversioned or for family/cluster."}},"required":["entityId","layer"]}}},"required":["entities"]} -
search_job_architectureKeyword search across job-architecture FAMILY, CLUSTER, ROLE and LEVEL. Matching is substring/full-text, NOT fuzzy or semantic ? the term must literally appear (no typo tolerance, no synonyms); for conceptual queries use 'semantic_search_job_architecture' instead. Does NOT search skills ? use 'search_skills' (keyword) or 'semantic_search_skills' (conceptual) for that. If unsure use a shorter substring (min 3 characters). Runs across every tenant-enabled language; results are grouped by locale (BCP-47 tag), each locale carrying entity buckets with locale-specific titles. Optionally restrict to specific layers and/or a single job architecture.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","description":"Free-text query. Must be non-blank."},"layers":{"type":"array","items":{"type":"string","enum":["FAMILY","CLUSTER","ROLE","LEVEL"]},"description":"Optional layer filter. Omit to search all layers. Pass a subset to narrow."},"jobArchitectureId":{"type":"string","description":"Optional job architecture UUID to scope the search to a single architecture. Omit for tenant-wide."},"limit":{"type":"integer","format":"int32","description":"Max hits per layer per locale. Defaults to 10, capped at 25."}},"required":["query"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"byLocale":{"type":"object","description":"Grouped by tenant locale (BCP-47 tag); titles reflect that locale."}}} -
search_reviewersSearch people who can be assigned as the reviewer of a role, by name. Returns minimal identity (id, first/last name; email only to tell two people apart). Use the returned id as reviewerUserId. Reviewer-eligible users only.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"searchTerm":{"type":"string","description":"Name (or part of a name) to search for."},"limit":{"type":"integer","format":"int32","description":"Max results (default 50)."}},"required":["searchTerm"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"emailAddress":{"type":["string","null"],"description":"Present only to disambiguate same-named people."},"firstName":{"type":"string"},"id":{"type":"string","description":"Pass verbatim as reviewerUserId to set_role_reviewer / set_level_reviewer."},"lastName":{"type":"string"}},"required":["firstName","id","lastName"]}}},"required":["items"]} -
search_skillsKeyword search of the global skill graph by title ? the same graph 'semantic_search_skills' queries, not the tenant's curated skill catalog. Matching is lexical with fuzzy tolerance (typos OK) but NOT semantic ? the query words must appear in the skill title. Use it to find canonical titles a term is known by (e.g. 'underwriting' surfaces every skill titled with it), which semantic ranking may bury. The search runs in exactly ONE language: set 'locale' to the user's locale (BCP-47 tag, e.g. 'en-US', 'fr-FR', 'fr-CA', 'de-DE'); titles are returned in that locale. For explorative tasks (assembling a skill set, checking coverage) do NOT rely on one mode: combine this with 'semantic_search_skills' query mode for conceptual matches, then expand the strongest anchors via its 'relatedToSkillId' mode ? a skill surfacing under several anchors is a stronger candidate. Use a returned skillId verbatim in later tool calls ? inventing skill ids is forbidden.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","description":"Skill title keywords. Must be non-blank."},"locale":{"type":"string","description":"BCP-47 locale to search in ? pass the user's language (e.g. 'en-US', 'fr-FR', 'fr-CA', 'de-DE'). Must be a tenant-enabled locale."},"limit":{"type":"integer","format":"int32","description":"Max hits. Defaults to 10, capped at 25."}},"required":["query","locale"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"locale":{"type":"string","description":"BCP-47 tag the search ran in; titles are in this locale."},"skills":{"description":"Matching skills; empty when none matched.","type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","description":"Use verbatim in surgical skillEdits. Inventing ids is forbidden."},"skillType":{"type":"string","description":"'hard' (technical), 'soft' (behavioural) or 'language'."},"title":{"type":"string"}},"required":["skillId","skillType","title"]}}},"required":["locale"]} -
semantic_search_job_architectureSemantic search over job-architecture FAMILY, CLUSTER and ROLE (NOT levels ? they are not semantically indexed; search the parent role). Matches by MEANING, not literal text ? use it for conceptual or paraphrased queries (e.g. "roles that do X") where keyword search would require guessing synonyms. Phrase 'query' as ONE focused concept or sentence ? a comma-separated keyword list dilutes the match. Provide EITHER 'query' (free-text concept) OR 'similarToItemId' (find items like an existing one), not both. Returns the topK hits ranked by similarity score; 'query' mode applies no minimum cutoff ? judge relevance from the scores and drop weak tail hits yourself. Each hit carries 'translations' with localized titles for every tenant language present on the item.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","description":"Free-text concept query. Provide this OR similarToItemId."},"similarToItemId":{"type":"string","description":"UUID of an existing FAMILY/CLUSTER/ROLE to find similar items to. Provide this OR query."},"layers":{"type":"array","items":{"type":"string","enum":["FAMILY","CLUSTER","ROLE"]},"description":"Restrict to these layers. Omit to search all of them."},"jobArchitectureId":{"type":"string","description":"Optional job architecture UUID to scope the search."},"topK":{"type":"integer","format":"int32","description":"Max hits. Defaults to 5, capped at 25."}},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string"},"jobArchitectureId":{"type":"string"},"jobArchitectureTitle":{"type":"string"},"layer":{"type":"string","description":"'FAMILY', 'CLUSTER' or 'ROLE'."},"similarityScore":{"type":"number","format":"double","description":"Cosine similarity; higher = more similar."},"title":{"type":"string","description":"English title."},"translations":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"description":"On families/clusters this is the main descriptive text ('structured' is always null there). On roles/levels it is only an internal working summary: machine-translated languages leave it blank ? blank is normal, not missing content ? and the profile content users see lives in 'structured' (which may itself contain a section named 'Description')."},"language":{"type":"string","description":"BCP-47 tag (e.g. 'en-US')."},"structured":{"description":"Content sections (e.g. responsibilities, qualifications); TASKS sections are excluded, see 'tasks'. Pass verbatim back to 'update_job_role' / 'update_job_level' on a partial edit to preserve them.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string"}},"required":["language","title"]}}},"required":["itemId","jobArchitectureId","jobArchitectureTitle","layer","similarityScore","title","translations"]}}},"required":["items"]} -
semantic_search_skillsSearch the global skill graph in one of two mutually-exclusive modes. Provide EITHER 'query' (free-text concept) OR 'relatedToSkillId' (find skills related to an existing one), not both. In 'query' mode it matches skills by MEANING, not literal text ? use it for conceptual or paraphrased queries (e.g. "leading distributed teams") where keyword search would require guessing synonyms; phrase 'query' as ONE focused concept. In 'relatedToSkillId' mode it returns skills the Skills API considers related to that skill id. The search runs in exactly ONE language: set 'locale' to the user's locale (BCP-47 tag, e.g. 'en-US', 'fr-FR', 'fr-CA', 'de-DE'); titles are returned in that locale. Use a returned skillId verbatim in later tool calls ? inventing skill ids is forbidden.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"locale":{"type":"string","description":"BCP-47 locale to search in ? pass the user's language (e.g. 'en-US', 'fr-FR', 'fr-CA', 'de-DE'). Must be a tenant-enabled locale."},"query":{"type":"string","description":"Free-text concept query. Provide this OR relatedToSkillId. Must be non-blank when given."},"relatedToSkillId":{"type":"string","description":"UUID of an existing skill to find related skills for. Provide this OR query."},"limit":{"type":"integer","format":"int32","description":"Max hits. Defaults to 10, capped at 25."}},"required":["locale"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"locale":{"type":"string","description":"BCP-47 tag the search ran in; titles are in this locale."},"skills":{"description":"Matching skills; empty when none matched.","type":"array","items":{"type":"object","properties":{"skillId":{"type":"string","description":"Use verbatim in surgical skillEdits. Inventing ids is forbidden."},"skillType":{"type":"string","description":"'hard' (technical), 'soft' (behavioural) or 'language'."},"title":{"type":"string"}},"required":["skillId","skillType","title"]}}},"required":["locale"]}
Job Architecture
Architect Write
Job Architecture
Architect Write
-
backfill_leveling_framework_translationsQueue a translation backfill for one job-architecture-scoped leveling framework. Only the languages missing on the framework, its tracks and its levels are filled in ? existing translations are left alone. Translation runs asynchronously, so the framework is unchanged when this returns. Returns the languages the framework will actually gain; an empty list means it already carries every language configured for the tenant, so nothing will change.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"frameworkId":{"type":"string","description":"Leveling framework UUID to translate."},"jobArchitectureId":{"type":"string","description":"Job architecture UUID the framework belongs to."}},"required":["frameworkId","jobArchitectureId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"frameworkId":{"type":"string"},"targetLanguages":{"description":"Language tags the framework will actually gain. Empty when it already carries every language configured for the tenant, in which case nothing will change.","type":"array","items":{"type":"string"}}},"required":["frameworkId","targetLanguages"]} -
bulk_assign_reviewersAssign or remove reviewers for up to 200 roles or levels. Provide 'reviewerUserId' per item to assign; OMIT it to remove that item's current reviewer. Attempts every item and returns only failures. Each item uses existing item-level permission rules.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture that must contain every requested role or level."},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","description":"Role or level UUID belonging to the requested job architecture."},"reviewerUserId":{"type":["string","null"],"description":"User UUID to assign as reviewer. Omit or null to remove the item's current reviewer."}},"required":["itemId"]},"description":"Role or level UUIDs with the reviewer UUID to assign, or without one to remove the current reviewer; 1-200 items."}},"required":["jobArchitectureId","items"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"failed":{"description":"Failures in input order; empty means every action succeeded.","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable backend error code."},"itemId":{"type":"string"},"message":{"type":"string"},"version":{"type":["integer","null"],"format":"int32","description":"Failed version; omitted for reviewer assignment."}},"required":["code","itemId","message"]}}}} -
bulk_publish_versionsPublish up to 200 explicit role or level versions. Attempts every item and returns only failures. Requires publish permission for each item.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture that must contain every requested role or level."},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","description":"Role or level UUID belonging to the requested job architecture."},"version":{"type":"integer","format":"int32","description":"Exact version to publish or approve."}},"required":["itemId","version"]},"description":"Role or level UUID and exact version pairs; 1-200 items."}},"required":["jobArchitectureId","items"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"failed":{"description":"Failures in input order; empty means every action succeeded.","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable backend error code."},"itemId":{"type":"string"},"message":{"type":"string"},"version":{"type":["integer","null"],"format":"int32","description":"Failed version; omitted for reviewer assignment."}},"required":["code","itemId","message"]}}}} -
create_job_clusterCreate a new job cluster under the given family. A full description is AI-generated asynchronously; 'description' is a short seed. Returns the new cluster's UUID.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"familyId":{"type":"string","description":"Parent family UUID."},"title":{"type":"string","description":"Cluster title, in 'languageTag' language."},"description":{"type":"string","description":"Short seed description the AI generation extends. Omit to generate from scratch."},"languageTag":{"type":"string","description":"BCP-47 tag of title/description. Defaults to 'en-US'."}},"required":["jobArchitectureId","familyId","title"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
create_job_familyCreate a new job family. A full description is AI-generated asynchronously; pass 'description' as a short seed the generation extends and improves. Returns the new family's UUID.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"title":{"type":"string","description":"Family title, in 'languageTag' language."},"description":{"type":"string","description":"Short seed description the AI generation extends. Omit to generate from scratch."},"languageTag":{"type":"string","description":"BCP-47 tag of title/description. Defaults to 'en-US'."}},"required":["jobArchitectureId","title"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
create_job_levelCreate a new job level under the given role with a draft job profile. See 'create_job_role' for the 'translation' input shape.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Parent role UUID."},"translation":{"type":"object","properties":{"description":{"type":["string","null"],"description":"Optional internal working summary, not rendered profile content. User-visible content belongs only in 'structured'. Plain text; markdown is not rendered. Leave null unless the user asked for a summary."},"languageTag":{"type":["string","null"],"description":"BCP-47 author language (e.g. 'en-US'). Null or blank = 'en-US'. Other tenant languages are filled in asynchronously."},"structured":{"description":"Content sections. Legal tags come from 'get_job_profile_template'.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string","description":"In the author's language. Visible to end users."}},"required":["title"],"description":"Origin-language job profile translation for the new level."},"detectSkills":{"type":"boolean","description":"true = detect skills asynchronously from the created profile content. Null or false = no detection."}},"required":["jobArchitectureId","roleId","translation"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
create_job_roleCreate a new job role under the given cluster with a draft job profile. The 'translation' input carries title, optional description, optional structured content sections and an optional origin language tag (defaults to 'en-US'). When structured sections are sent, set each element's 'id' to a section id from 'get_job_profile_template' ? the profile is then linked to the template and tags are derived server-side. Pass detectSkills=true to detect skills asynchronously from the created content; leave it unset for seed-style creates, whose skills come from generation. Other tenant languages are translated asynchronously. Returns the new role's UUID.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"clusterId":{"type":"string","description":"Parent cluster UUID."},"translation":{"type":"object","properties":{"description":{"type":["string","null"],"description":"Optional internal working summary, not rendered profile content. User-visible content belongs only in 'structured'. Plain text; markdown is not rendered. Leave null unless the user asked for a summary."},"languageTag":{"type":["string","null"],"description":"BCP-47 author language (e.g. 'en-US'). Null or blank = 'en-US'. Other tenant languages are filled in asynchronously."},"structured":{"description":"Content sections. Legal tags come from 'get_job_profile_template'.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string","description":"In the author's language. Visible to end users."}},"required":["title"],"description":"Origin-language job profile translation for the new role."},"detectSkills":{"type":"boolean","description":"true = detect skills asynchronously from the created profile content. Null or false = no detection."}},"required":["jobArchitectureId","clusterId","translation"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
create_leveling_frameworkCreate a new leveling framework. When 'jobArchitectureId' is omitted the framework is tenant-scoped (visible to the caller's tenant). When given, the framework is bound to that job architecture. Inputs are English-only; other tenant languages are translated asynchronously. Returns the persisted framework view.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"input":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217 (e.g. EUR). Defaults to EUR when omitted; an unrecognised code is rejected."},"description":{"type":"string","description":"In English."},"name":{"type":"string","description":"In English."},"tracks":{"description":"May be empty for an outline-only framework.","type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"]},"levels":{"description":"Lowest seniority first. Each level keeps the 'level' number it carries; levels without one are numbered by their position (1-based), so a track that does not start at 1 must send 'level'.","type":"array","items":{"type":"object","properties":{"compensation":{"description":"The level's pay. Give the level's default pay as the entry without a 'region', and one further entry per regional band. Omit entirely to leave the level's pay untouched on update, or unset on create.","type":"array","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217. Defaults to the framework's currency."},"fringeBenefits":{"type":["string","null"]},"longTermIncentive":{"type":["string","null"]},"name":{"type":["string","null"],"description":"Label for the band, e.g. \"Denmark\". Defaults to the region when omitted."},"payType":{"type":["string","null"],"description":"SALARIED or HOURLY. Defaults to SALARIED."},"region":{"type":["string","null"],"description":"Country or region this band applies to, e.g. \"DK\" or \"Singapore\". Leave it out for the level's default pay ? exactly one entry may omit it."},"salaryMaximum":{"type":["number","null"]},"salaryMidpoint":{"type":["number","null"],"description":"Defaults to the midpoint between minimum and maximum when omitted."},"salaryMinimum":{"type":["number","null"]},"targetBonus":{"type":["string","null"],"description":"Free text, e.g. \"10%\" ? varies by region, so it sits on the band."}}}},"description":{"type":["string","null"]},"employmentType":{"type":["string","null"],"description":"TARIF or AT. Applies to the whole level. Defaults to TARIF when pay is given."},"level":{"type":["integer","null"],"format":"int32","description":"The number this level carries in its track. Omit to number it by its position in the list (1-based) ? send it whenever a track starts above 1 or leaves gaps."},"name":{"type":"string","description":"In English."},"payGrade":{"type":["string","null"],"description":"Applies to the whole level, every pay band included."},"progressionCriteria":{"type":["string","null"]}},"required":["name"]}},"name":{"type":"string","description":"In English."},"trackId":{"type":["string","null"],"description":"Omit when creating. When updating, pass the track's existing 'trackId' so it keeps its identity ? a track written back without its id is a different track, and any role that had selected the old one loses that selection."}},"required":["name"]}},"translateOtherLanguages":{"type":"boolean","description":"False = keep the framework English-only; skip the automatic backfill into the tenant's other languages."},"type":{"type":"string","description":"MARKET, UNION or CUSTOM. Defaults to MARKET."}},"required":["description","name"],"description":"Framework definition (English-only)."},"jobArchitectureId":{"type":"string","description":"Optional job architecture UUID to scope the framework to."}},"required":["input"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"currency":{"type":["string","null"],"description":"ISO 4217, for salary data on the framework's levels."},"description":{"type":"string"},"frameworkId":{"type":"string"},"jobArchitectureId":{"type":["string","null"],"description":"Null for tenant- or globally-scoped frameworks."},"lastUpdate":{"type":"string","format":"date-time"},"name":{"type":"string"},"ownerScope":{"type":"string","description":"GLOBAL (system-wide) or TENANT (owned by the caller's tenant)."},"tracks":{"description":"Career tracks (lanes), in defined ordering.","type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"levels":{"description":"Ordered by ascending level number.","type":"array","items":{"type":"object","properties":{"compensation":{"description":"The level's pay. The entry without a 'region' is the level's default pay; any further entries are regional bands. Empty when no pay has been set.","type":"array","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217. A band may use a different currency from the framework's."},"fringeBenefits":{"type":["string","null"]},"longTermIncentive":{"type":["string","null"]},"name":{"type":["string","null"],"description":"Label for the band, e.g. \"Denmark\". Absent on the level's default pay."},"payType":{"type":["string","null"],"description":"SALARIED or HOURLY."},"region":{"type":["string","null"],"description":"Country or region this band applies to. Absent on the level's default pay."},"salaryMaximum":{"type":["number","null"]},"salaryMidpoint":{"type":["number","null"]},"salaryMinimum":{"type":["number","null"]},"targetBonus":{"type":["string","null"]}}}},"description":{"type":"string"},"employmentType":{"type":["string","null"],"description":"TARIF or AT. Applies to the whole level."},"level":{"type":"integer","format":"int32","description":"1-based within the track."},"name":{"type":"string"},"payGrade":{"type":["string","null"],"description":"Applies to the whole level, every pay band included."},"progressionCriteria":{"type":["string","null"]}},"required":["description","level","name"]}},"name":{"type":"string"},"trackId":{"type":"string"}},"required":["description","levels","name","trackId"]}},"type":{"type":"string","description":"MARKET, UNION or CUSTOM."}},"required":["createdAt","description","frameworkId","lastUpdate","name","ownerScope","tracks","type"]} -
delete_job_profile_templateDelete the customer-managed job profile template assigned to a job architecture. Throws when the template does not exist or does not belong to the given job architecture. Cobrainer-managed templates are NOT deletable from this tool.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID the template belongs to."},"templateId":{"type":"string","description":"Template UUID to delete."}},"required":["jobArchitectureId","templateId"]} -
detect_skillsRe-detect skills for a role or level against a candidate job profile translation. Returns the newly detected skills and their delta (added / removed / changed) versus the diff baseline. Useful before calling 'update_job_role' / 'update_job_level' so the new version's skills stay aligned with the updated content. Required 'additionalPrompt' picks the detector mode: type=REDETECT for a fresh run ignoring prior skills, type=ADJUST to anchor against the current skills and apply optional 'userInput' free-text guidance. Optional 'version' anchors the diff baseline against that specific version of the item; when omitted, the item's current version is used. A version that does not exist on the item fails with a 404.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"translation":{"type":"object","properties":{"description":{"type":["string","null"],"description":"Optional internal working summary, not rendered profile content. User-visible content belongs only in 'structured'. Plain text; markdown is not rendered. Leave null unless the user asked for a summary."},"languageTag":{"type":["string","null"],"description":"BCP-47 author language (e.g. 'en-US'). Null or blank = 'en-US'. Other tenant languages are filled in asynchronously."},"structured":{"description":"Content sections. Legal tags come from 'get_job_profile_template'.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string","description":"In the author's language. Visible to end users."}},"required":["title"],"description":"Candidate translation used as detection input."},"additionalPrompt":{"type":"object","properties":{"type":{"type":"string","enum":["REDETECT","ADJUST"],"description":"'REDETECT' = fresh run ignoring the item's current skills; 'ADJUST' = anchor on current skills and apply 'userInput' as guidance."},"userInput":{"type":["string","null"],"description":"Free-text guidance; only for 'ADJUST'."}},"required":["type"],"description":"Steering prompt for the detector. 'REDETECT' forces a fresh run ignoring prior skills; 'ADJUST' applies optional 'userInput' as free-text guidance."},"version":{"type":"integer","format":"int32","description":"Optional version number whose skills are used as the diff baseline. Defaults to the item's current version."}},"required":["jobArchitectureId","itemId","translation","additionalPrompt"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpDetectedSkill":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Competency grouping; preserved when persisting."},"confidence":{"type":["number","null"],"format":"float","description":"Detector confidence (0.0-1.0). Informational only."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillId":{"type":"string","description":"Must reference an existing catalog skill."},"textOccurrences":{"description":"Source text fragments that triggered detection. Ignored on input.","type":["array","null"],"items":{"type":"string"}},"title":{"type":"string","description":"English title. Ignored on input."},"type":{"type":"string","description":"'hard', 'soft' or 'language'. Ignored on input."}},"required":["level","skillId","title","type"]}},"type":"object","properties":{"addedSkills":{"description":"Informational delta vs the item's current skills.","type":"array","items":{"$ref":"#/$defs/McpDetectedSkill"}},"changedSkills":{"description":"Informational delta vs the item's current skills.","type":"array","items":{"$ref":"#/$defs/McpDetectedSkill"}},"detectedSkills":{"description":"Full inferred set. Pass verbatim as the 'skills' argument of 'update_job_role' / 'update_job_level' to persist.","type":"array","items":{"$ref":"#/$defs/McpDetectedSkill"}},"removedSkills":{"description":"Informational delta vs the item's current skills.","type":"array","items":{"$ref":"#/$defs/McpDetectedSkill"}}},"required":["addedSkills","changedSkills","detectedSkills","removedSkills"]} -
generate_job_levelCreate a new job level under the given role and trigger full AI generation of its job profile asynchronously (career-framework aware). See 'generate_job_role'. Returns the new level's UUID.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Parent role UUID."},"title":{"type":"string","description":"Level title, in 'languageTag' language."},"description":{"type":"string","description":"Short seed description the AI generation builds on. Omit to generate from scratch."},"languageTag":{"type":"string","description":"BCP-47 tag of title/description. Defaults to 'en-US'."}},"required":["jobArchitectureId","roleId","title"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
generate_job_roleCreate a new job role under the given cluster and trigger full AI generation of its job profile (content, skills, translations) asynchronously. 'description' is a short seed the generation builds on. Unlike 'create_job_role', which stores a caller-provided draft profile as-is. Returns the new role's UUID.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"clusterId":{"type":"string","description":"Parent cluster UUID."},"title":{"type":"string","description":"Role title, in 'languageTag' language."},"description":{"type":"string","description":"Short seed description the AI generation builds on. Omit to generate from scratch."},"languageTag":{"type":"string","description":"BCP-47 tag of title/description. Defaults to 'en-US'."}},"required":["jobArchitectureId","clusterId","title"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
generate_work_taskAppend a work task to a role's or level's TASKS section from a title. The title is stored verbatim; description, workflow, classification, effort and skills are AI-generated asynchronously, so the task comes back QUEUED and fills in later (re-read via 'get_nodes'). Requires a TASKS section on the item's latest version, otherwise fails with 400. Creates a new item version.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"title":{"type":"string","description":"Max 256 characters; stored verbatim."},"language":{"type":"string","description":"BCP-47 tag of 'title'. Defaults to 'en-US'."}},"required":["jobArchitectureId","itemId","title"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}} -
publish_level_versionPublish a specific version of a job level.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"levelId":{"type":"string","description":"Level UUID."},"version":{"type":"integer","format":"int32","description":"Version number to publish."}},"required":["jobArchitectureId","levelId","version"]} -
publish_role_versionPublish a specific version of a job role. Requires CAN_PUBLISH_JOB_ARCHITECTURE_ITEM.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Role UUID."},"version":{"type":"integer","format":"int32","description":"Version number to publish."}},"required":["jobArchitectureId","roleId","version"]} -
put_job_profile_templateCreate or replace the customer-managed job profile template for a job architecture. Each job architecture owns at most one template; passing a 'templateId' that does not yet exist creates it, otherwise the existing template is overwritten in place. Sections may either reference Cobrainer-managed sections by their sectionId (type=COBRAINER ? re-uses the source structure and guidance, the supplied 'name' overrides the displayed name only) or be tenant-defined (type=CUSTOM ? uses the supplied 'name', 'guidance', 'contentType' and item limits). English-only input; other tenant languages are retranslated asynchronously. Throws when the supplied content fails the configured risk evaluation. Cobrainer-managed templates are NOT mutable from this tool; use the REST admin API instead.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpCustomTemplateSectionInput":{"type":"object","properties":{"contentType":{"type":"string","description":"BULLET_POINTS, SENTENCES or TASKS. For COBRAINER sections must equal the section's contentType as returned by get_job_profile_template (or by the Cobrainer template tools when the architecture has no template yet); it cannot be changed. CUSTOM TASKS sections cannot be created via this tool yet."},"guidance":{"type":"string","description":"Authoring guidance. Ignored for COBRAINER sections."},"maxNumberOfItems":{"type":"integer","format":"int32","description":"Ignored for COBRAINER sections."},"minNumberOfItems":{"type":"integer","format":"int32","description":"Ignored for COBRAINER sections."},"name":{"type":"string","description":"In English. For COBRAINER sections overrides the displayed name only."},"sectionId":{"type":["string","null"],"description":"Required for COBRAINER (must reference an existing Cobrainer section); optional for CUSTOM ? generated when omitted."},"type":{"type":"string","description":"'COBRAINER' (re-uses a Cobrainer-managed section by id) or 'CUSTOM' (tenant-defined)."}},"required":["contentType","guidance","maxNumberOfItems","minNumberOfItems","name","type"]},"McpSkillLimits":{"type":"object","properties":{"expectedNumberOfSkills":{"type":"integer","format":"int32","description":"Target skill count ? aim for this when detecting skills."},"maximumNumberOfSkills":{"type":"integer","format":"int32","description":"Hard cap."},"skillDetectionPreference":{"type":["string","null"],"description":"Free-text soft preference biasing skill detection (max 5000 chars)."}},"required":["expectedNumberOfSkills","maximumNumberOfSkills"]}},"type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID the template belongs to."},"templateId":{"type":"string","description":"Template UUID. Generate a new UUID to create; pass the existing one to update in place."},"input":{"type":"object","properties":{"cobrainerJobTemplateId":{"type":["string","null"],"description":"Omit = keep stored link or auto-detect; null = detach."},"description":{"type":"string","description":"In English."},"jobLevelSections":{"description":"In desired ordering.","type":"array","items":{"$ref":"#/$defs/McpCustomTemplateSectionInput"}},"jobRoleSections":{"description":"In desired ordering.","type":"array","items":{"$ref":"#/$defs/McpCustomTemplateSectionInput"}},"levelSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"name":{"type":"string","description":"In English."},"roleSkillLimits":{"$ref":"#/$defs/McpSkillLimits"}},"required":["description","jobLevelSections","jobRoleSections","levelSkillLimits","name","roleSkillLimits"],"description":"Template definition (English-only)."}},"required":["jobArchitectureId","templateId","input"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpJobProfileTemplateSection":{"type":"object","properties":{"contentType":{"type":"string","description":"BULLET_POINTS, SENTENCES or TASKS. Never author structured text for TASKS sections."},"guidance":{"type":"string","description":"Follow when authoring this section."},"maxNumberOfItems":{"type":"integer","format":"int32"},"minNumberOfItems":{"type":"integer","format":"int32"},"name":{"type":"string","description":"English name (e.g. 'Responsibilities')."},"names":{"description":"Localized display names.","type":"array","items":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 tag."},"text":{"type":"string"}},"required":["language","text"]}},"origin":{"type":"string","description":"e.g. SYSTEM, CUSTOM."},"sectionId":{"type":"string","description":"Use as the structured element 'id' when authoring this section."}},"required":["contentType","guidance","maxNumberOfItems","minNumberOfItems","name","origin","sectionId"]},"McpSkillLimits":{"type":"object","properties":{"expectedNumberOfSkills":{"type":"integer","format":"int32","description":"Target skill count ? aim for this when detecting skills."},"maximumNumberOfSkills":{"type":"integer","format":"int32","description":"Hard cap."},"skillDetectionPreference":{"type":["string","null"],"description":"Free-text soft preference biasing skill detection (max 5000 chars)."}},"required":["expectedNumberOfSkills","maximumNumberOfSkills"]}},"type":"object","properties":{"description":{"type":"string"},"jobLevelSections":{"description":"Sections to author for a job level.","type":"array","items":{"$ref":"#/$defs/McpJobProfileTemplateSection"}},"jobRoleSections":{"description":"Sections to author for a job role.","type":"array","items":{"$ref":"#/$defs/McpJobProfileTemplateSection"}},"levelSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"name":{"type":"string"},"roleSkillLimits":{"$ref":"#/$defs/McpSkillLimits"},"templateId":{"type":"string"}},"required":["description","jobLevelSections","jobRoleSections","levelSkillLimits","name","roleSkillLimits","templateId"]} -
regenerate_work_taskFully regenerate one referenced work task in a new QUEUED version. Omit 'title' to preserve its current title; optional 'instruction' guides the generated content. The item is repinned to the new task version in the same change.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"taskId":{"type":"string","description":"Referenced work task UUID."},"title":{"type":"string","description":"Optional replacement title, max 256 characters."},"language":{"type":"string","description":"BCP-47 language of the title/instruction. Defaults to 'en-US'."},"instruction":{"type":"string","description":"Optional plain-text guidance for this regeneration."}},"required":["jobArchitectureId","itemId","taskId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}} -
remove_work_taskRemove a work task from the item's TASKS section. Never hard-deletes: the task and its version history are retained, only the reference on the new item version is dropped. Remaining tasks are re-numbered. Requires a TASKS section on the item.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"taskId":{"type":"string"}},"required":["jobArchitectureId","itemId","taskId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}} -
reorder_work_tasksReorder the item's work tasks. 'orderedTaskIds' must be a full permutation of the current 'tasks' ids (no additions, omissions or duplicates); a mismatch fails with 400 listing the expected ids. Creates a new item version; task content is untouched. Requires a TASKS section on the item.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"orderedTaskIds":{"type":"array","items":{"type":"string"},"description":"Every current task UUID exactly once, in the desired order."}},"required":["jobArchitectureId","itemId","orderedTaskIds"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}} -
resolve_commentsResolve user comments that the latest change addressed. Pass the root comment UUIDs to resolve and the version number they were addressed in (the version just created by 'update_job_role'/'update_job_level'). Already-resolved or unknown ids are skipped. Only resolve comments the change actually addressed.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID the comments belong to."},"commentIds":{"type":"array","items":{"type":"string"},"description":"Root comment UUIDs to resolve."},"version":{"type":"integer","format":"int32","description":"Version the comments are resolved in (the version just created)."}},"required":["jobArchitectureId","itemId","commentIds","version"]} -
resolve_work_task_commentsResolve addressed work-task comment threads in the newly created task version. Bad or already-resolved ids are skipped.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID the task belongs to."},"taskId":{"type":"string","description":"Work task UUID."},"commentIds":{"type":"array","items":{"type":"string"},"description":"Root comment UUIDs to resolve."},"version":{"type":"integer","format":"int32","description":"New task version that addressed the comments."}},"required":["jobArchitectureId","itemId","taskId","commentIds","version"]} -
set_items_archivedArchive ('archived'=true) or restore ('archived'=false) job roles and levels in one call. 'itemIds' may mix role and level UUIDs; each id is classified server-side. Archiving a role also archives its active levels; restoring a level also restores its archived parent role. Archived items are hidden but recoverable. Ids already in the requested state, ids that are not roles or levels, and ids outside the given job architecture are skipped.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemIds":{"type":"array","items":{"type":"string"},"description":"Role and level UUIDs to change, mixed freely."},"archived":{"type":"boolean","description":"true to archive, false to restore."}},"required":["jobArchitectureId","itemIds","archived"]} -
set_level_reviewerSet, change, or remove the reviewer of a job LEVEL. Provide 'reviewerUserId' (resolve via 'search_reviewers') to assign or change the reviewer; OMIT it to remove the current reviewer. Reviewer-only change ? does not create a new content version. Fails with 403 if I may not change this level's reviewer.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"levelId":{"type":"string","description":"Level UUID whose reviewer to set."},"reviewerUserId":{"type":"string","description":"User UUID of the new reviewer (from search_reviewers). Omit/null to remove the current reviewer."}},"required":["jobArchitectureId","levelId"]} -
set_role_reviewerSet, change, or remove the reviewer of a job ROLE. Provide 'reviewerUserId' (resolve via 'search_reviewers') to assign or change the reviewer; OMIT it to remove the current reviewer. Reviewer-only change ? does not create a new content version. Fails with 403 if I may not change this role's reviewer.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Role UUID whose reviewer to set."},"reviewerUserId":{"type":"string","description":"User UUID of the new reviewer (from search_reviewers). Omit/null to remove the current reviewer."}},"required":["jobArchitectureId","roleId"]} -
unpublish_level_versionUnpublish a specific version of a job level.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"levelId":{"type":"string","description":"Level UUID."},"version":{"type":"integer","format":"int32","description":"Version number to unpublish."}},"required":["jobArchitectureId","levelId","version"]} -
unpublish_role_versionUnpublish a specific version of a job role.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Role UUID."},"version":{"type":"integer","format":"int32","description":"Version number to unpublish."}},"required":["jobArchitectureId","roleId","version"]} -
unreview_level_versionRemove the reviewed status from a specific version of a job level.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"levelId":{"type":"string","description":"Level UUID."},"version":{"type":"integer","format":"int32","description":"Version number."}},"required":["jobArchitectureId","levelId","version"]} -
unreview_role_versionRemove the reviewed status from a specific version of a job role.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Role UUID."},"version":{"type":"integer","format":"int32","description":"Version number."}},"required":["jobArchitectureId","roleId","version"]} -
update_job_clusterUpdate a job cluster's title and description in the given language. Pass the FULL new content ? title and description together replace the cluster's current content in that language. Other tenant languages are retranslated asynchronously unless 'translateOtherLanguages' is false.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"clusterId":{"type":"string","description":"Cluster UUID."},"title":{"type":"string","description":"New cluster title, in 'languageTag' language."},"description":{"type":"string","description":"New full cluster description, in 'languageTag' language."},"languageTag":{"type":"string","description":"BCP-47 tag of title/description. Defaults to 'en-US'."},"translateOtherLanguages":{"type":"boolean","description":"Whether to auto-translate this change into the tenant's other languages. Defaults to true. Pass false to change only the given language and leave the others unchanged."}},"required":["jobArchitectureId","clusterId","title","description"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
update_job_familyUpdate a job family's title and description in the given language. Pass the FULL new content ? title and description together replace the family's current content in that language. Other tenant languages are retranslated asynchronously unless 'translateOtherLanguages' is false.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"familyId":{"type":"string","description":"Family UUID."},"title":{"type":"string","description":"New family title, in 'languageTag' language."},"description":{"type":"string","description":"New full family description, in 'languageTag' language."},"languageTag":{"type":"string","description":"BCP-47 tag of title/description. Defaults to 'en-US'."},"translateOtherLanguages":{"type":"boolean","description":"Whether to auto-translate this change into the tenant's other languages. Defaults to true. Pass false to change only the given language and leave the others unchanged."}},"required":["jobArchitectureId","familyId","title","description"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
update_job_levelCreate a new version of a level's job profile in the translation's origin language (defaults to 'en-US'). See 'update_job_role' for the 'translation' and 'skills' input shapes.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"levelId":{"type":"string","description":"Level UUID."},"translation":{"type":"object","properties":{"description":{"type":["string","null"],"description":"Optional internal working summary, not rendered profile content. User-visible content belongs only in 'structured'. Plain text; markdown is not rendered. Leave null unless the user asked for a summary."},"languageTag":{"type":["string","null"],"description":"BCP-47 author language (e.g. 'en-US'). Null or blank = 'en-US'. Other tenant languages are filled in asynchronously."},"structured":{"description":"Content sections. Legal tags come from 'get_job_profile_template'.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string","description":"In the author's language. Visible to end users."}},"required":["title"],"description":"New origin-language translation; produces a new version."},"skills":{"type":"array","items":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Competency grouping; preserved when persisting."},"confidence":{"type":["number","null"],"format":"float","description":"Detector confidence (0.0-1.0). Informational only."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillId":{"type":"string","description":"Must reference an existing catalog skill."},"textOccurrences":{"description":"Source text fragments that triggered detection. Ignored on input.","type":["array","null"],"items":{"type":"string"}},"title":{"type":"string","description":"English title. Ignored on input."},"type":{"type":"string","description":"'hard', 'soft' or 'language'. Ignored on input."}},"required":["level","skillId","title","type"]},"description":"Skills to attach to the new version. Pass the 'detectedSkills' list from 'detect_skills' verbatim. Omit or pass null to leave the current skill set unchanged. An empty list clears all skills."},"sectionTags":{"type":"array","items":{"type":"object","properties":{"names":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 tag."},"text":{"type":"string"}},"required":["language","text"]}},"sectionId":{"type":"string","description":"Matches the 'id' of structured content elements in this section."},"type":{"type":"string","description":"Content format: BULLET_POINTS, SENTENCES or TASKS. TASKS content lives in 'tasks'; never author structured text for it."}},"required":["names","sectionId"]},"description":"Section tags describing the structured content sections of the new version. Pass the level's 'sectionTags' (as returned by 'get_nodes') verbatim. Omit, pass null, or pass an empty list to leave the current section tags unchanged."},"comment":{"type":"string","description":"One short sentence, in the translation's language, summarising what changed in this update. Stored as the new version's change note. Omit or pass null to leave it empty."},"translateOtherLanguages":{"type":"boolean","description":"Whether to auto-translate this change into the tenant's other languages. Defaults to true. Pass false to change only the translation's own language and leave the others unchanged."},"translationInstructions":{"type":"array","items":{"type":"object","properties":{"instruction":{"type":"string","description":"Wording changes to apply in that language's translation, e.g. reviewer feedback on the existing translation."},"languageTag":{"type":"string","description":"BCP-47 tag of the target language this instruction applies to."}},"required":["instruction","languageTag"]},"description":"Per-target-language wording instructions applied during the automatic retranslation (e.g. reviewer feedback on a specific language's text). Ignored when 'translateOtherLanguages' is false. Each entry: languageTag (BCP-47) + instruction."},"replacementTaskTitles":{"type":"array","items":{"type":"string"},"description":"Full regeneration only. Replaces the complete work-task set: every current task and its generated content is dropped and new tasks are generated asynchronously from these titles. Omit/null preserves the current tasks. Never pass current titles verbatim; edit single tasks with the *_work_task tools."}},"required":["jobArchitectureId","levelId","translation"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
update_job_roleCreate a new version of a role's job profile in the translation's origin language (defaults to 'en-US'). Pass the full translation object: title, optional description, optional structured content sections. Optionally pass 'skills' (e.g. the 'detectedSkills' list returned by 'detect_skills') to persist them on the new version. Other tenant languages are retranslated asynchronously unless 'translateOtherLanguages' is false.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Role UUID."},"translation":{"type":"object","properties":{"description":{"type":["string","null"],"description":"Optional internal working summary, not rendered profile content. User-visible content belongs only in 'structured'. Plain text; markdown is not rendered. Leave null unless the user asked for a summary."},"languageTag":{"type":["string","null"],"description":"BCP-47 author language (e.g. 'en-US'). Null or blank = 'en-US'. Other tenant languages are filled in asynchronously."},"structured":{"description":"Content sections. Legal tags come from 'get_job_profile_template'.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string","description":"In the author's language. Visible to end users."}},"required":["title"],"description":"New origin-language translation; produces a new version."},"skills":{"type":"array","items":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Competency grouping; preserved when persisting."},"confidence":{"type":["number","null"],"format":"float","description":"Detector confidence (0.0-1.0). Informational only."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillId":{"type":"string","description":"Must reference an existing catalog skill."},"textOccurrences":{"description":"Source text fragments that triggered detection. Ignored on input.","type":["array","null"],"items":{"type":"string"}},"title":{"type":"string","description":"English title. Ignored on input."},"type":{"type":"string","description":"'hard', 'soft' or 'language'. Ignored on input."}},"required":["level","skillId","title","type"]},"description":"Skills to attach to the new version. Pass the 'detectedSkills' list from 'detect_skills' verbatim. Omit or pass null to leave the current skill set unchanged. An empty list clears all skills."},"sectionTags":{"type":"array","items":{"type":"object","properties":{"names":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 tag."},"text":{"type":"string"}},"required":["language","text"]}},"sectionId":{"type":"string","description":"Matches the 'id' of structured content elements in this section."},"type":{"type":"string","description":"Content format: BULLET_POINTS, SENTENCES or TASKS. TASKS content lives in 'tasks'; never author structured text for it."}},"required":["names","sectionId"]},"description":"Section tags describing the structured content sections of the new version. Pass the role's 'sectionTags' (as returned by 'get_nodes') verbatim. Omit, pass null, or pass an empty list to leave the current section tags unchanged."},"comment":{"type":"string","description":"One short sentence, in the translation's language, summarising what changed in this update. Stored as the new version's change note. Omit or pass null to leave it empty."},"translateOtherLanguages":{"type":"boolean","description":"Whether to auto-translate this change into the tenant's other languages. Defaults to true. Pass false to change only the translation's own language and leave the others unchanged."},"translationInstructions":{"type":"array","items":{"type":"object","properties":{"instruction":{"type":"string","description":"Wording changes to apply in that language's translation, e.g. reviewer feedback on the existing translation."},"languageTag":{"type":"string","description":"BCP-47 tag of the target language this instruction applies to."}},"required":["instruction","languageTag"]},"description":"Per-target-language wording instructions applied during the automatic retranslation (e.g. reviewer feedback on a specific language's text). Ignored when 'translateOtherLanguages' is false. Each entry: languageTag (BCP-47) + instruction."},"replacementTaskTitles":{"type":"array","items":{"type":"string"},"description":"Full regeneration only. Replaces the complete work-task set: every current task and its generated content is dropped and new tasks are generated asynchronously from these titles. Omit/null preserves the current tasks. Never pass current titles verbatim; edit single tasks with the *_work_task tools."}},"required":["jobArchitectureId","roleId","translation"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
update_leveling_frameworkReplace the content of an existing leveling framework. When 'jobArchitectureId' is omitted the tenant-scoped framework is updated; when given, the job-architecture-scoped framework is updated. Tracks and levels are fully replaced ? pass the desired final state. Inputs are English-only; other tenant languages are translated asynchronously. Returns the persisted framework view.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"frameworkId":{"type":"string","description":"Leveling framework UUID to update."},"input":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217 (e.g. EUR). Defaults to EUR when omitted; an unrecognised code is rejected."},"description":{"type":"string","description":"In English."},"name":{"type":"string","description":"In English."},"tracks":{"description":"May be empty for an outline-only framework.","type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"]},"levels":{"description":"Lowest seniority first. Each level keeps the 'level' number it carries; levels without one are numbered by their position (1-based), so a track that does not start at 1 must send 'level'.","type":"array","items":{"type":"object","properties":{"compensation":{"description":"The level's pay. Give the level's default pay as the entry without a 'region', and one further entry per regional band. Omit entirely to leave the level's pay untouched on update, or unset on create.","type":"array","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217. Defaults to the framework's currency."},"fringeBenefits":{"type":["string","null"]},"longTermIncentive":{"type":["string","null"]},"name":{"type":["string","null"],"description":"Label for the band, e.g. \"Denmark\". Defaults to the region when omitted."},"payType":{"type":["string","null"],"description":"SALARIED or HOURLY. Defaults to SALARIED."},"region":{"type":["string","null"],"description":"Country or region this band applies to, e.g. \"DK\" or \"Singapore\". Leave it out for the level's default pay ? exactly one entry may omit it."},"salaryMaximum":{"type":["number","null"]},"salaryMidpoint":{"type":["number","null"],"description":"Defaults to the midpoint between minimum and maximum when omitted."},"salaryMinimum":{"type":["number","null"]},"targetBonus":{"type":["string","null"],"description":"Free text, e.g. \"10%\" ? varies by region, so it sits on the band."}}}},"description":{"type":["string","null"]},"employmentType":{"type":["string","null"],"description":"TARIF or AT. Applies to the whole level. Defaults to TARIF when pay is given."},"level":{"type":["integer","null"],"format":"int32","description":"The number this level carries in its track. Omit to number it by its position in the list (1-based) ? send it whenever a track starts above 1 or leaves gaps."},"name":{"type":"string","description":"In English."},"payGrade":{"type":["string","null"],"description":"Applies to the whole level, every pay band included."},"progressionCriteria":{"type":["string","null"]}},"required":["name"]}},"name":{"type":"string","description":"In English."},"trackId":{"type":["string","null"],"description":"Omit when creating. When updating, pass the track's existing 'trackId' so it keeps its identity ? a track written back without its id is a different track, and any role that had selected the old one loses that selection."}},"required":["name"]}},"translateOtherLanguages":{"type":"boolean","description":"False = keep the framework English-only; skip the automatic backfill into the tenant's other languages."},"type":{"type":"string","description":"MARKET, UNION or CUSTOM. Defaults to MARKET."}},"required":["description","name"],"description":"Replacement framework definition (English-only)."},"jobArchitectureId":{"type":"string","description":"Optional job architecture UUID to scope the update to."}},"required":["frameworkId","input"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"currency":{"type":["string","null"],"description":"ISO 4217, for salary data on the framework's levels."},"description":{"type":"string"},"frameworkId":{"type":"string"},"jobArchitectureId":{"type":["string","null"],"description":"Null for tenant- or globally-scoped frameworks."},"lastUpdate":{"type":"string","format":"date-time"},"name":{"type":"string"},"ownerScope":{"type":"string","description":"GLOBAL (system-wide) or TENANT (owned by the caller's tenant)."},"tracks":{"description":"Career tracks (lanes), in defined ordering.","type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"levels":{"description":"Ordered by ascending level number.","type":"array","items":{"type":"object","properties":{"compensation":{"description":"The level's pay. The entry without a 'region' is the level's default pay; any further entries are regional bands. Empty when no pay has been set.","type":"array","items":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217. A band may use a different currency from the framework's."},"fringeBenefits":{"type":["string","null"]},"longTermIncentive":{"type":["string","null"]},"name":{"type":["string","null"],"description":"Label for the band, e.g. \"Denmark\". Absent on the level's default pay."},"payType":{"type":["string","null"],"description":"SALARIED or HOURLY."},"region":{"type":["string","null"],"description":"Country or region this band applies to. Absent on the level's default pay."},"salaryMaximum":{"type":["number","null"]},"salaryMidpoint":{"type":["number","null"]},"salaryMinimum":{"type":["number","null"]},"targetBonus":{"type":["string","null"]}}}},"description":{"type":"string"},"employmentType":{"type":["string","null"],"description":"TARIF or AT. Applies to the whole level."},"level":{"type":"integer","format":"int32","description":"1-based within the track."},"name":{"type":"string"},"payGrade":{"type":["string","null"],"description":"Applies to the whole level, every pay band included."},"progressionCriteria":{"type":["string","null"]}},"required":["description","level","name"]}},"name":{"type":"string"},"trackId":{"type":"string"}},"required":["description","levels","name","trackId"]}},"type":{"type":"string","description":"MARKET, UNION or CUSTOM."}},"required":["createdAt","description","frameworkId","lastUpdate","name","ownerScope","tracks","type"]} -
update_work_taskEdit fields of one work task; omitted fields stay unchanged. Mints a new task version and a new item version; other tenant languages are retranslated asynchronously. Only FINISHED tasks can be edited (409 while generation is pending). Requires a TASKS section on the item.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"taskId":{"type":"string","description":"Obtain from the item's 'tasks'."},"title":{"type":"string","description":"Max 256 characters."},"description":{"type":"string"},"workflow":{"type":"object","properties":{"steps":{"description":"1..100 steps in execution order. Replaces the whole workflow.","type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"physicality":{"type":["string","null"],"description":"'physical' or 'non-physical'."},"title":{"type":"string"}},"required":["description","title"]}}},"required":["steps"],"description":"Replaces the whole workflow."},"classification":{"type":"object","properties":{"reasoning":{"type":"string"},"value":{"type":"string","description":"'contribution' or 'commodity'."}},"required":["reasoning","value"]},"estimatedEffort":{"type":"object","properties":{"maximumHoursPerWeek":{"type":"number"},"minimumHoursPerWeek":{"type":"number","description":"Hours per week, > 0 and <= 168; minimum <= maximum."},"reasoning":{"type":"string"}},"required":["maximumHoursPerWeek","minimumHoursPerWeek","reasoning"]},"requiredSkills":{"type":"array","items":{"type":"string"},"description":"Replaces the current set. Existing skills keep their level; new ones default to 3."}},"required":["jobArchitectureId","itemId","taskId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}}
Job Architecture
Reviewer Write
Job Architecture
Reviewer Write
-
bulk_approve_versionsApprove up to 200 explicit role or level versions. Attempts every item and returns only failures. Each approval uses existing reviewer permissions.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture that must contain every requested role or level."},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","description":"Role or level UUID belonging to the requested job architecture."},"version":{"type":"integer","format":"int32","description":"Exact version to publish or approve."}},"required":["itemId","version"]},"description":"Role or level UUID and exact version pairs; 1-200 items."}},"required":["jobArchitectureId","items"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"failed":{"description":"Failures in input order; empty means every action succeeded.","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable backend error code."},"itemId":{"type":"string"},"message":{"type":"string"},"version":{"type":["integer","null"],"format":"int32","description":"Failed version; omitted for reviewer assignment."}},"required":["code","itemId","message"]}}}} -
bulk_assign_reviewersAssign or remove reviewers for up to 200 roles or levels already assigned to the caller. Provide 'reviewerUserId' per item to assign; OMIT it to remove that item's current reviewer. Attempts every item and returns only failures.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture that must contain every requested role or level."},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","description":"Role or level UUID belonging to the requested job architecture."},"reviewerUserId":{"type":["string","null"],"description":"User UUID to assign as reviewer. Omit or null to remove the item's current reviewer."}},"required":["itemId"]},"description":"Role or level UUIDs with the reviewer UUID to assign, or without one to remove the current reviewer; 1-200 items."}},"required":["jobArchitectureId","items"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"failed":{"description":"Failures in input order; empty means every action succeeded.","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable backend error code."},"itemId":{"type":"string"},"message":{"type":"string"},"version":{"type":["integer","null"],"format":"int32","description":"Failed version; omitted for reviewer assignment."}},"required":["code","itemId","message"]}}}} -
detect_skillsRe-detect skills for a role or level assigned to me for review, against a candidate translation. Returns the newly detected skills and the delta (added / removed / changed) versus the diff baseline. Fails with 403 if I am not the assigned reviewer. Useful before calling 'update_job_role' / 'update_job_level' to align skills with the new content. Required 'additionalPrompt' picks the detector mode: type=REDETECT for a fresh run ignoring prior skills, type=ADJUST to anchor against the current skills and apply optional 'userInput' free-text guidance. Optional 'version' anchors the diff baseline against that specific version of the item; when omitted, the item's current version is used. A version that does not exist on the item fails with a 404.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"translation":{"type":"object","properties":{"description":{"type":["string","null"],"description":"Optional internal working summary, not rendered profile content. User-visible content belongs only in 'structured'. Plain text; markdown is not rendered. Leave null unless the user asked for a summary."},"languageTag":{"type":["string","null"],"description":"BCP-47 author language (e.g. 'en-US'). Null or blank = 'en-US'. Other tenant languages are filled in asynchronously."},"structured":{"description":"Content sections. Legal tags come from 'get_job_profile_template'.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string","description":"In the author's language. Visible to end users."}},"required":["title"],"description":"Candidate translation used as detection input."},"additionalPrompt":{"type":"object","properties":{"type":{"type":"string","enum":["REDETECT","ADJUST"],"description":"'REDETECT' = fresh run ignoring the item's current skills; 'ADJUST' = anchor on current skills and apply 'userInput' as guidance."},"userInput":{"type":["string","null"],"description":"Free-text guidance; only for 'ADJUST'."}},"required":["type"],"description":"Steering prompt for the detector. 'REDETECT' forces a fresh run ignoring prior skills; 'ADJUST' applies optional 'userInput' as free-text guidance."},"version":{"type":"integer","format":"int32","description":"Optional version number whose skills are used as the diff baseline. Defaults to the item's current version."}},"required":["jobArchitectureId","itemId","translation","additionalPrompt"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpDetectedSkill":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Competency grouping; preserved when persisting."},"confidence":{"type":["number","null"],"format":"float","description":"Detector confidence (0.0-1.0). Informational only."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillId":{"type":"string","description":"Must reference an existing catalog skill."},"textOccurrences":{"description":"Source text fragments that triggered detection. Ignored on input.","type":["array","null"],"items":{"type":"string"}},"title":{"type":"string","description":"English title. Ignored on input."},"type":{"type":"string","description":"'hard', 'soft' or 'language'. Ignored on input."}},"required":["level","skillId","title","type"]}},"type":"object","properties":{"addedSkills":{"description":"Informational delta vs the item's current skills.","type":"array","items":{"$ref":"#/$defs/McpDetectedSkill"}},"changedSkills":{"description":"Informational delta vs the item's current skills.","type":"array","items":{"$ref":"#/$defs/McpDetectedSkill"}},"detectedSkills":{"description":"Full inferred set. Pass verbatim as the 'skills' argument of 'update_job_role' / 'update_job_level' to persist.","type":"array","items":{"$ref":"#/$defs/McpDetectedSkill"}},"removedSkills":{"description":"Informational delta vs the item's current skills.","type":"array","items":{"$ref":"#/$defs/McpDetectedSkill"}}},"required":["addedSkills","changedSkills","detectedSkills","removedSkills"]} -
generate_work_taskAppend a work task to the TASKS section of a role or level assigned to me for review, from a title. The title is stored verbatim; the rest of the task is AI-generated asynchronously, so it comes back QUEUED and fills in later (re-read via 'get_nodes'). Requires a TASKS section on the item's latest version (400 otherwise). Fails with 403 if I am not the assigned reviewer.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"title":{"type":"string","description":"Max 256 characters; stored verbatim."},"language":{"type":"string","description":"BCP-47 tag of 'title'. Defaults to 'en-US'."}},"required":["jobArchitectureId","itemId","title"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}} -
regenerate_work_taskFully regenerate one work task on an item assigned to me for review in a new QUEUED version. Omit 'title' to preserve its current title; optional 'instruction' guides the generated content. The item is repinned in the same change.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"taskId":{"type":"string","description":"Referenced work task UUID."},"title":{"type":"string","description":"Optional replacement title, max 256 characters."},"language":{"type":"string","description":"BCP-47 language of the title/instruction. Defaults to 'en-US'."},"instruction":{"type":"string","description":"Optional plain-text guidance for this regeneration."}},"required":["jobArchitectureId","itemId","taskId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}} -
remove_work_taskRemove a work task from the TASKS section of an item assigned to me for review. Never hard-deletes: task and version history are retained, only the reference is dropped. Fails with 403 if I am not the assigned reviewer. Requires a TASKS section on the item.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"taskId":{"type":"string"}},"required":["jobArchitectureId","itemId","taskId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}} -
reorder_work_tasksReorder the work tasks of an item assigned to me for review. 'orderedTaskIds' must be a full permutation of the current 'tasks' ids; a mismatch fails with 400 listing the expected ids. Creates a new item version. Requires a TASKS section on the item. Fails with 403 if I am not the assigned reviewer.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"orderedTaskIds":{"type":"array","items":{"type":"string"},"description":"Every current task UUID exactly once, in the desired order."}},"required":["jobArchitectureId","itemId","orderedTaskIds"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}} -
resolve_commentsResolve user comments addressed by my latest change to an item assigned to me for review. Pass the root comment UUIDs and the version they were addressed in (the version just created). Already-resolved or unknown ids are skipped. Fails with 403 if I am not the assigned reviewer.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID the comments belong to."},"commentIds":{"type":"array","items":{"type":"string"},"description":"Root comment UUIDs to resolve."},"version":{"type":"integer","format":"int32","description":"Version the comments are resolved in (the version just created)."}},"required":["jobArchitectureId","itemId","commentIds","version"]} -
resolve_work_task_commentsResolve addressed work-task comment threads in the newly created task version. Bad or already-resolved ids are skipped.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID the task belongs to."},"taskId":{"type":"string","description":"Work task UUID."},"commentIds":{"type":"array","items":{"type":"string"},"description":"Root comment UUIDs to resolve."},"version":{"type":"integer","format":"int32","description":"New task version that addressed the comments."}},"required":["jobArchitectureId","itemId","taskId","commentIds","version"]} -
review_level_versionMark a specific version of a job level as reviewed. Only callable by the reviewer assigned to the underlying job profile.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"levelId":{"type":"string","description":"Level UUID."},"version":{"type":"integer","format":"int32","description":"Version number."}},"required":["jobArchitectureId","levelId","version"]} -
review_role_versionMark a specific version of a job role as reviewed. Only callable by the reviewer assigned to the underlying job profile.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Role UUID."},"version":{"type":"integer","format":"int32","description":"Version number."}},"required":["jobArchitectureId","roleId","version"]} -
set_level_reviewerSet, change, or remove the reviewer of a job LEVEL assigned to me. See 'set_role_reviewer' for the 'reviewerUserId' semantics (omit to remove). Reviewer-only change ? does not create a new content version. Fails with 403 if I am not the assigned reviewer of this level.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"levelId":{"type":"string","description":"Level UUID whose reviewer to set."},"reviewerUserId":{"type":"string","description":"User UUID of the new reviewer (from search_reviewers). Omit/null to remove the current reviewer."}},"required":["jobArchitectureId","levelId"]} -
set_role_reviewerSet, change, or remove the reviewer of a job ROLE assigned to me. Provide 'reviewerUserId' (resolve via 'search_reviewers') to assign or change the reviewer; OMIT it to remove the current reviewer. Reviewer-only change ? does not create a new content version. Fails with 403 if I am not the assigned reviewer of this role.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Role UUID whose reviewer to set."},"reviewerUserId":{"type":"string","description":"User UUID of the new reviewer (from search_reviewers). Omit/null to remove the current reviewer."}},"required":["jobArchitectureId","roleId"]} -
update_job_levelCreate a new version of a level assigned to me for review. See 'update_job_role' for the translation and 'skills' input shapes. Fails with 403 if I am not the assigned reviewer.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"levelId":{"type":"string","description":"Level UUID."},"translation":{"type":"object","properties":{"description":{"type":["string","null"],"description":"Optional internal working summary, not rendered profile content. User-visible content belongs only in 'structured'. Plain text; markdown is not rendered. Leave null unless the user asked for a summary."},"languageTag":{"type":["string","null"],"description":"BCP-47 author language (e.g. 'en-US'). Null or blank = 'en-US'. Other tenant languages are filled in asynchronously."},"structured":{"description":"Content sections. Legal tags come from 'get_job_profile_template'.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string","description":"In the author's language. Visible to end users."}},"required":["title"],"description":"New origin-language translation; produces a new version."},"skills":{"type":"array","items":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Competency grouping; preserved when persisting."},"confidence":{"type":["number","null"],"format":"float","description":"Detector confidence (0.0-1.0). Informational only."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillId":{"type":"string","description":"Must reference an existing catalog skill."},"textOccurrences":{"description":"Source text fragments that triggered detection. Ignored on input.","type":["array","null"],"items":{"type":"string"}},"title":{"type":"string","description":"English title. Ignored on input."},"type":{"type":"string","description":"'hard', 'soft' or 'language'. Ignored on input."}},"required":["level","skillId","title","type"]},"description":"Skills to attach to the new version. Pass the 'detectedSkills' list from 'detect_skills' verbatim. Omit or pass null to leave the current skill set unchanged. An empty list clears all skills."},"comment":{"type":"string","description":"One short sentence, in the translation's language, summarising what changed in this update. Stored as the new version's change note. Omit or pass null to leave it empty."},"translateOtherLanguages":{"type":"boolean","description":"Whether to auto-translate this change into the tenant's other languages. Defaults to true. Pass false to change only the translation's own language and leave the others unchanged."},"translationInstructions":{"type":"array","items":{"type":"object","properties":{"instruction":{"type":"string","description":"Wording changes to apply in that language's translation, e.g. reviewer feedback on the existing translation."},"languageTag":{"type":"string","description":"BCP-47 tag of the target language this instruction applies to."}},"required":["instruction","languageTag"]},"description":"Per-target-language wording instructions applied during the automatic retranslation (e.g. reviewer feedback on a specific language's text). Ignored when 'translateOtherLanguages' is false. Each entry: languageTag (BCP-47) + instruction."},"replacementTaskTitles":{"type":"array","items":{"type":"string"},"description":"Full regeneration only. Replaces the complete work-task set: every current task and its generated content is dropped and new tasks are generated asynchronously from these titles. Omit/null preserves the current tasks. Never pass current titles verbatim; edit single tasks with the *_work_task tools."}},"required":["jobArchitectureId","levelId","translation"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
update_job_roleCreate a new version of a role assigned to me for review. Pass the full translation object (title, optional description, optional structured content sections, optional origin languageTag defaulting to 'en-US'). Optionally pass 'skills' (e.g. the 'detectedSkills' list returned by 'detect_skills') to persist them on the new version. Fails with 403 if I am not the assigned reviewer.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"roleId":{"type":"string","description":"Role UUID."},"translation":{"type":"object","properties":{"description":{"type":["string","null"],"description":"Optional internal working summary, not rendered profile content. User-visible content belongs only in 'structured'. Plain text; markdown is not rendered. Leave null unless the user asked for a summary."},"languageTag":{"type":["string","null"],"description":"BCP-47 author language (e.g. 'en-US'). Null or blank = 'en-US'. Other tenant languages are filled in asynchronously."},"structured":{"description":"Content sections. Legal tags come from 'get_job_profile_template'.","type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable section-instance id. Defaults to 'tag' when omitted."},"tag":{"type":"string","description":"Section tag (e.g. 'responsibilities'). Must match a section from 'get_job_profile_template'."},"value":{"type":"string","description":"Plain text, in the author's language."}},"required":["tag","value"]}},"title":{"type":"string","description":"In the author's language. Visible to end users."}},"required":["title"],"description":"New origin-language translation; produces a new version."},"skills":{"type":"array","items":{"type":"object","properties":{"competencyId":{"type":["string","null"],"description":"Competency grouping; preserved when persisting."},"confidence":{"type":["number","null"],"format":"float","description":"Detector confidence (0.0-1.0). Informational only."},"level":{"type":"integer","description":"Required proficiency level (1..5; language skills 1..6)."},"skillId":{"type":"string","description":"Must reference an existing catalog skill."},"textOccurrences":{"description":"Source text fragments that triggered detection. Ignored on input.","type":["array","null"],"items":{"type":"string"}},"title":{"type":"string","description":"English title. Ignored on input."},"type":{"type":"string","description":"'hard', 'soft' or 'language'. Ignored on input."}},"required":["level","skillId","title","type"]},"description":"Skills to attach to the new version. Pass the 'detectedSkills' list from 'detect_skills' verbatim. Omit or pass null to leave the current skill set unchanged. An empty list clears all skills."},"comment":{"type":"string","description":"One short sentence, in the translation's language, summarising what changed in this update. Stored as the new version's change note. Omit or pass null to leave it empty."},"translateOtherLanguages":{"type":"boolean","description":"Whether to auto-translate this change into the tenant's other languages. Defaults to true. Pass false to change only the translation's own language and leave the others unchanged."},"translationInstructions":{"type":"array","items":{"type":"object","properties":{"instruction":{"type":"string","description":"Wording changes to apply in that language's translation, e.g. reviewer feedback on the existing translation."},"languageTag":{"type":"string","description":"BCP-47 tag of the target language this instruction applies to."}},"required":["instruction","languageTag"]},"description":"Per-target-language wording instructions applied during the automatic retranslation (e.g. reviewer feedback on a specific language's text). Ignored when 'translateOtherLanguages' is false. Each entry: languageTag (BCP-47) + instruction."},"replacementTaskTitles":{"type":"array","items":{"type":"string"},"description":"Full regeneration only. Replaces the complete work-task set: every current task and its generated content is dropped and new tasks are generated asynchronously from these titles. Omit/null preserves the current tasks. Never pass current titles verbatim; edit single tasks with the *_work_task tools."}},"required":["jobArchitectureId","roleId","translation"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"itemId":{"type":"string","description":"Created or updated role/level UUID."},"version":{"type":["integer","null"],"format":"int32","description":"New version number. Null when no new version was created (e.g. reviewer-only update)."}},"required":["itemId"]} -
update_work_taskEdit fields of one work task on an item assigned to me for review; omitted fields stay unchanged. Mints a new task version and item version; other tenant languages are retranslated asynchronously. Only FINISHED tasks can be edited (409 while pending). Requires a TASKS section on the item. Fails with 403 if I am not the assigned reviewer.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"itemId":{"type":"string","description":"Role or level UUID."},"taskId":{"type":"string","description":"Obtain from the item's 'tasks'."},"title":{"type":"string","description":"Max 256 characters."},"description":{"type":"string"},"workflow":{"type":"object","properties":{"steps":{"description":"1..100 steps in execution order. Replaces the whole workflow.","type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"physicality":{"type":["string","null"],"description":"'physical' or 'non-physical'."},"title":{"type":"string"}},"required":["description","title"]}}},"required":["steps"],"description":"Replaces the whole workflow."},"classification":{"type":"object","properties":{"reasoning":{"type":"string"},"value":{"type":"string","description":"'contribution' or 'commodity'."}},"required":["reasoning","value"]},"estimatedEffort":{"type":"object","properties":{"maximumHoursPerWeek":{"type":"number"},"minimumHoursPerWeek":{"type":"number","description":"Hours per week, > 0 and <= 168; minimum <= maximum."},"reasoning":{"type":"string"}},"required":["maximumHoursPerWeek","minimumHoursPerWeek","reasoning"]},"requiredSkills":{"type":"array","items":{"type":"string"},"description":"Replaces the current set. Existing skills keep their level; new ones default to 3."}},"required":["jobArchitectureId","itemId","taskId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"generationState":{"type":["string","null"],"description":"QUEUED right after generation or regeneration; content arrives asynchronously."},"itemVersion":{"type":["integer","null"],"format":"int32","description":"Role/level version the task section is pinned on after this call."},"orderedTaskIds":{"description":"Final order after 'reorder_work_tasks'.","type":["array","null"],"items":{"type":"string"}},"removed":{"type":["boolean","null"]},"taskId":{"type":["string","null"]},"version":{"type":["integer","null"],"format":"int32","description":"New pinned task version after update or regeneration."}}}
Company Settings
Read + Write
Company Settings
Read + Write
-
get_company_profileRead the organization profile of the current tenant: company name, per-language description, per-language top priorities and number of employees. Use it before proposing a profile change so you can show the user what changes and leave everything else untouched. Language tags are BCP-47 ('en-US', 'de-DE') ? pass them back verbatim to 'update_company_profile'.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpTranslatedText":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 language tag, e.g. 'en-US'."},"text":{"type":"string"}},"required":["language","text"]}},"type":"object","properties":{"description":{"description":"Company description per language. Empty when not set.","type":"array","items":{"$ref":"#/$defs/McpTranslatedText"}},"name":{"type":"string"},"priorities":{"description":"Top priorities per language. Empty when not set.","type":"array","items":{"$ref":"#/$defs/McpTranslatedText"}},"size":{"type":"integer","format":"int32","description":"Number of employees."}},"required":["name","size"]} -
get_company_settingsRead the company-wide settings: skills synchronization mode (PERMISSIVE / RESTRICTED), whether warning signals are visible, whether short skill descriptions are preferred, the custom job-architecture terminology (job families / clusters / roles / levels) and the skill proficiency level terminology. A null terminology layer means no override, i.e. the default wording. Read it before every 'update_company_settings' call and pass the language tags back verbatim.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpPluralTerm":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 language tag, e.g. 'en-US'."},"many":{"type":"string","description":"Plural label, e.g. 'Job Families'."},"one":{"type":"string","description":"Singular label, e.g. 'Job Family'."}},"required":["language","many","one"]},"McpTerm":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 language tag, e.g. 'en-US'."},"value":{"type":"string"}},"required":["language","value"]}},"type":"object","properties":{"jobArchitectureTerminology":{"type":["object","null"],"properties":{"jobClusters":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}},"jobFamilies":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}},"jobLevels":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}},"jobRoles":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}}}},"preferShortSkillDescriptions":{"type":"boolean"},"skillProficiencyLevelTerminology":{"type":["object","null"],"properties":{"advanced":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"basic":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"domainExpert":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"professional":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"qualified":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}}}},"skillsSynchronizationMode":{"type":"string","description":"PERMISSIVE: employees may add skills beyond their job profile. RESTRICTED: only job-profile skills."},"warningSignalsVisible":{"type":"boolean"}},"required":["preferShortSkillDescriptions","skillsSynchronizationMode","warningSignalsVisible"]} -
get_job_architecture_metadataRead the company profile stored on one job architecture ? the answers given during its generation: company name, description, size, priorities, business units and primary goals. This is separate from the organization profile ('get_company_profile') and only steers generation for that job architecture. 'metadata' is null when the job architecture has none yet.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."}},"required":["jobArchitectureId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"metadata":{"type":["object","null"],"properties":{"businessUnits":{"type":"array","items":{"type":"string"}},"companyDescription":{"type":"string"},"companyExecutiveRolesInFamily":{"type":"boolean"},"companyName":{"type":["string","null"]},"companyPriorities":{"type":["string","null"]},"companySize":{"type":"integer","format":"int32"},"jobArchitectureId":{"type":"string"},"primaryGoalOtherText":{"type":["string","null"]},"primaryGoals":{"description":"Primary goal enum names as stored by the api (PrimaryGoalType).","type":"array","items":{"type":"string"}}},"required":["companyExecutiveRolesInFamily","companySize","jobArchitectureId"]}}} -
get_organization_languagesList the tenant's languages with their enabled flag and which one is the default. Use it before writing terminology or profile texts so you cover every enabled language and never invent a tag the tenant does not use. Each 'language' is a BCP-47 tag to pass back verbatim.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"enabledOnly":{"type":"boolean","description":"True (default) returns only enabled languages; false returns only disabled ones."}},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"languages":{"type":"array","items":{"type":"object","properties":{"enabled":{"type":"boolean"},"isDefault":{"type":"boolean"},"language":{"type":"string","description":"BCP-47 language tag."}},"required":["enabled","isDefault","language"]}}},"required":["languages"]} -
update_company_profileChange the organization profile (name, per-language description, per-language top priorities, number of employees) and return the profile as stored afterwards. Every null field in 'update' is left untouched; a non-null 'description' or 'priorities' replaces that list in full, so send the complete per-language set including the languages you are not changing. Language tags come from 'get_organization_languages' and must be passed verbatim.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpTranslatedText":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 language tag, e.g. 'en-US'."},"text":{"type":"string"}},"required":["language","text"]}},"type":"object","properties":{"update":{"type":"object","properties":{"description":{"description":"Replaces the full per-language description list. Null keeps the current list.","type":["array","null"],"items":{"$ref":"#/$defs/McpTranslatedText"}},"name":{"type":["string","null"],"description":"New company name (max 50 chars). Null keeps the current name."},"priorities":{"description":"Replaces the full per-language priorities list. Null keeps the current list.","type":["array","null"],"items":{"$ref":"#/$defs/McpTranslatedText"}},"size":{"type":["integer","null"],"format":"int32","description":"Number of employees (>= 1). Null keeps the current size."}},"description":"Fields to change. Omit or null-out everything that stays as it is."}},"required":["update"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpTranslatedText":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 language tag, e.g. 'en-US'."},"text":{"type":"string"}},"required":["language","text"]}},"type":"object","properties":{"description":{"description":"Company description per language. Empty when not set.","type":"array","items":{"$ref":"#/$defs/McpTranslatedText"}},"name":{"type":"string"},"priorities":{"description":"Top priorities per language. Empty when not set.","type":"array","items":{"$ref":"#/$defs/McpTranslatedText"}},"size":{"type":"integer","format":"int32","description":"Number of employees."}},"required":["name","size"]} -
update_company_settingsChange the company-wide settings (skills synchronization mode, warning signals, short skill descriptions, job-architecture terminology, skill proficiency terminology) and return the settings as stored afterwards. Null fields are untouched. Inside a terminology object, a non-null layer or level replaces that layer's full per-language list while null layers keep their current wording; pass an empty list to clear a layer back to the default.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpPluralTerm":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 language tag, e.g. 'en-US'."},"many":{"type":"string","description":"Plural label, e.g. 'Job Families'."},"one":{"type":"string","description":"Singular label, e.g. 'Job Family'."}},"required":["language","many","one"]},"McpTerm":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 language tag, e.g. 'en-US'."},"value":{"type":"string"}},"required":["language","value"]}},"type":"object","properties":{"update":{"type":"object","properties":{"jobArchitectureTerminology":{"type":["object","null"],"properties":{"jobClusters":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}},"jobFamilies":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}},"jobLevels":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}},"jobRoles":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}}}},"preferShortSkillDescriptions":{"type":["boolean","null"]},"skillProficiencyLevelTerminology":{"type":["object","null"],"properties":{"advanced":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"basic":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"domainExpert":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"professional":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"qualified":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}}}},"skillsSynchronizationMode":{"type":["string","null"],"description":"PERMISSIVE or RESTRICTED. Null keeps the current mode."},"warningSignalsVisible":{"type":["boolean","null"]}},"description":"Fields to change. Omit or null-out everything that stays as it is."}},"required":["update"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","$defs":{"McpPluralTerm":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 language tag, e.g. 'en-US'."},"many":{"type":"string","description":"Plural label, e.g. 'Job Families'."},"one":{"type":"string","description":"Singular label, e.g. 'Job Family'."}},"required":["language","many","one"]},"McpTerm":{"type":"object","properties":{"language":{"type":"string","description":"BCP-47 language tag, e.g. 'en-US'."},"value":{"type":"string"}},"required":["language","value"]}},"type":"object","properties":{"jobArchitectureTerminology":{"type":["object","null"],"properties":{"jobClusters":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}},"jobFamilies":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}},"jobLevels":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}},"jobRoles":{"type":["array","null"],"items":{"$ref":"#/$defs/McpPluralTerm"}}}},"preferShortSkillDescriptions":{"type":"boolean"},"skillProficiencyLevelTerminology":{"type":["object","null"],"properties":{"advanced":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"basic":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"domainExpert":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"professional":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}},"qualified":{"type":["array","null"],"items":{"$ref":"#/$defs/McpTerm"}}}},"skillsSynchronizationMode":{"type":"string","description":"PERMISSIVE: employees may add skills beyond their job profile. RESTRICTED: only job-profile skills."},"warningSignalsVisible":{"type":"boolean"}},"required":["preferShortSkillDescriptions","skillsSynchronizationMode","warningSignalsVisible"]} -
update_job_architecture_metadataChange the company profile stored on one job architecture ? the generation answers, not the organization profile ? and return it as stored afterwards. Null fields are untouched; 'businessUnits' and 'primaryGoals' replace their list in full. The job architecture itself is never renamed by this tool. Read 'get_job_architecture_metadata' first and reuse its 'jobArchitectureId' verbatim.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"update":{"type":"object","properties":{"businessUnits":{"description":"Replaces the full list.","type":["array","null"],"items":{"type":"string"}},"companyDescription":{"type":["string","null"]},"companyExecutiveRolesInFamily":{"type":["boolean","null"]},"companyName":{"type":["string","null"],"description":"Max 120 chars."},"companyPriorities":{"type":["string","null"]},"companySize":{"type":["integer","null"],"format":"int32","description":"1..10000000."},"primaryGoalOtherText":{"type":["string","null"]},"primaryGoals":{"description":"Replaces the full list. PrimaryGoalType enum names.","type":["array","null"],"items":{"type":"string"}}},"description":"Fields to change. Omit or null-out everything that stays as it is."}},"required":["jobArchitectureId","update"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"metadata":{"type":["object","null"],"properties":{"businessUnits":{"type":"array","items":{"type":"string"}},"companyDescription":{"type":"string"},"companyExecutiveRolesInFamily":{"type":"boolean"},"companyName":{"type":["string","null"]},"companyPriorities":{"type":["string","null"]},"companySize":{"type":"integer","format":"int32"},"jobArchitectureId":{"type":"string"},"primaryGoalOtherText":{"type":["string","null"]},"primaryGoals":{"description":"Primary goal enum names as stored by the api (PrimaryGoalType).","type":"array","items":{"type":"string"}}},"required":["companyExecutiveRolesInFamily","companySize","jobArchitectureId"]}}} -
update_job_architecture_titleRename one job architecture ? its own displayed name, the one shown in the job-architecture list ? and return the name as stored afterwards. This is NOT the company profile stored on the architecture; use 'update_job_architecture_metadata' for that. The name is written for the given language only and the other languages keep their current name, so rename each language the user cares about explicitly. Read 'get_jsa_overview' first and reuse its 'jobArchitectureId' verbatim.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string","description":"Job architecture UUID."},"update":{"type":"object","properties":{"languageTag":{"type":["string","null"],"description":"BCP-47 tag the title is written in. Defaults to 'en-US'."},"title":{"type":"string","description":"The new name of the job architecture. 1..256 characters, not blank."}},"required":["title"],"description":"The new name and the language it is written in."}},"required":["jobArchitectureId","update"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobArchitectureId":{"type":"string"},"languageTag":{"type":"string"},"title":{"type":"string"}},"required":["jobArchitectureId","languageTag","title"]}
User Management
Read + Write
User Management
Read + Write
-
delete_tenant_userRemove one member from the tenant and from the identity provider, and return the id that was removed. This cannot be undone and is never done in bulk: confirm the exact person with the user first, resolve their id with 'list_tenant_members' and pass it verbatim. Callers cannot remove their own account.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"userId":{"type":"string","description":"User UUID from 'list_tenant_members'."}},"required":["userId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"userId":{"type":"string"}},"required":["userId"]} -
get_invitation_optionsList what an invitation may be created with in this tenant: the assignable roles and the available invitation methods (EMAIL sends a sign-in link, SSO relies on the tenant's identity provider). Call it before 'invite_users' and pass 'roleId' and the method verbatim ? a role or method that is not listed here is rejected. When 'methodsUnavailableReason' is set the methods could not be checked (the tenant's user pool did not answer) ? the roles are still exact, so go ahead and propose the invitation without a method; the invitation itself reports per person whether it could be sent.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"methods":{"description":"Available invitation methods: EMAIL and/or SSO. Empty when none could be determined.","type":"array","items":{"type":"string"}},"methodsUnavailableReason":{"type":["string","null"],"description":"Set when the invitation methods could not be determined; explains why. Roles are still valid."},"roles":{"description":"Roles that may be assigned to an invitee. Use roleId verbatim in invite_users.","type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"roleId":{"type":"string"}},"required":["label","roleId"]}}},"required":["methods","roles"]} -
invite_usersInvite people to the tenant and return one result per entry, in the order they were sent. Entries are processed independently: an entry that fails (for example because the address already belongs to a member) carries an 'error' and the others still go through, so always read every result before reporting back. 'reinvited' true means an open invitation for that address was re-sent rather than created. Roles and method must come from 'get_invitation_options'. Between 1 and 20 entries per call.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"invitations":{"type":"array","items":{"type":"object","properties":{"emailAddress":{"type":"string"},"firstName":{"type":"string"},"jobTitle":{"type":["string","null"]},"lastName":{"type":"string"},"method":{"type":["string","null"],"description":"EMAIL or SSO. Null = tenant default."},"roles":{"description":"Role ids from get_invitation_options. Empty = default role.","type":"array","items":{"type":"string"}}},"required":["emailAddress","firstName","lastName"]},"description":"People to invite (1-20), each with email address, first and last name."}},"required":["invitations"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"emailAddress":{"type":"string"},"error":{"type":["string","null"],"description":"Set when this entry failed (e.g. already a member). Other entries still succeed."},"invitationId":{"type":["string","null"],"description":"Invitation id when created or re-sent."},"reinvited":{"type":"boolean","description":"True when an existing pending invitation was re-sent instead of created."}},"required":["emailAddress"]}}},"required":["results"]} -
list_pending_invitationsList the invitations of the current tenant that are still open ? nobody has signed up with them yet ? with id, email address, job title, roles, state and creation time. Use a returned 'id' verbatim as the 'invitationId' for 'revoke_invitation'. People who already accepted are members and appear in 'list_tenant_members' instead. Capped at the 200 most recently created ? say so rather than concluding an address was never invited when the list is full.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"invitations":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":"string","description":"ISO-8601 instant."},"emailAddress":{"type":"string"},"id":{"type":"string"},"jobTitle":{"type":["string","null"]},"roles":{"type":"array","items":{"type":"string"}},"state":{"type":"string","description":"UserInvitationState value."}},"required":["createdAt","emailAddress","id","roles","state"]}}},"required":["invitations"]} -
list_tenant_membersLook up members of the current tenant ? active users and people with an open invitation ? with id, name, email address, roles, status and last sign-in. Always pass 'searchTerm' with the name or email the user mentioned; only page through the directory when the user explicitly asked for a full list. Use a returned 'id' verbatim as the 'userId' for 'delete_tenant_user'. Summarise what you found rather than repeating the whole list back.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"searchTerm":{"type":"string","description":"Filters by name or email address. Omit only for a deliberate full listing."},"page":{"type":"integer","format":"int32","description":"0-based page number. Defaults to 0."},"pageSize":{"type":"integer","format":"int32","description":"Members per page (1-100). Defaults to 25."}},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"emailAddress":{"type":["string","null"]},"firstName":{"type":["string","null"]},"id":{"type":"string"},"lastName":{"type":["string","null"]},"lastSignedIn":{"type":["string","null"],"description":"ISO-8601 instant or null when the user never signed in."},"roles":{"description":"Role ids, e.g. 'job_architect', 'reviewer', 'user'.","type":"array","items":{"type":"string"}},"status":{"type":"string","description":"TenantMemberStatus value, e.g. ACTIVE or INVITED."}},"required":["id","roles","status"]}},"page":{"type":"integer","format":"int32"},"pageSize":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int64"}},"required":["members","page","pageSize","total"]} -
revoke_invitationWithdraw one open invitation so its sign-in link stops working, and return the id that was revoked. Resolve the id with 'list_pending_invitations' and pass it verbatim. This does not touch members who already accepted ? use 'delete_tenant_user' for those.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"invitationId":{"type":"string","description":"Invitation UUID from 'list_pending_invitations'."}},"required":["invitationId"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"invitationId":{"type":"string"}},"required":["invitationId"]}
Skill Catalog
Read + Write
Skill Catalog
Read + Write
-
get_skill_catalog_statisticsCount the skills in the tenant's skill catalog, optionally narrowed to one job architecture, role, level, status, skill type, source or search term. This is the right answer to every 'how many', 'do we have any' and 'is there anything to review' question ? it returns four numbers and never a list, so prefer it over 'search_skill_catalog' whenever the user does not need names. 'synced' counts Approved (SYNC) and Automatic (SYNC_WHEN_IN_PROFILE) TOGETHER; when the user needs them apart, call 'search_skill_catalog' with statusFilter=["SYNC"] and read its 'total'. No filter is required ? the unfiltered count is the size of the whole catalog. Runs one at a time per user: never batch it with another catalog read.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"searchTerm":{"type":"string","description":"Free-text skill search, at most 100 characters."},"statusFilter":{"type":"array","items":{"type":"string"},"description":"Sync statuses to count: SYNC, SYNC_WHEN_IN_PROFILE, NOT_SYNCED, NEEDS_REVIEW."},"jobArchitectureId":{"type":"string","description":"Job architecture UUID to scope the count to one architecture."},"roleIds":{"type":"array","items":{"type":"string"},"description":"Role item UUIDs (at most 50)."},"levelIds":{"type":"array","items":{"type":"string"},"description":"Level item UUIDs (at most 50)."},"skillTypes":{"type":"array","items":{"type":"string"},"description":"Skill types: hard, soft, language."},"sources":{"type":"array","items":{"type":"string"},"description":"How the skill entered the catalog: attributed or manual."}},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"appliedFilters":{"description":"The filters that were applied, in 'name=value' form. Empty means the whole catalog was counted.","type":"array","items":{"type":"string"}},"disabled":{"type":"integer","format":"int32","description":"Disabled (NOT_SYNCED) skills."},"needsReview":{"type":"integer","format":"int32","description":"Skills still awaiting review (NEEDS_REVIEW)."},"synced":{"type":"integer","format":"int32","description":"Approved (SYNC) and Automatic (SYNC_WHEN_IN_PROFILE) counted together."},"total":{"type":"integer","format":"int32","description":"Skills in the catalog matching the filters."}},"required":["disabled","needsReview","synced","total"]} -
lookup_skillsResolve up to 50 skill UUIDs to their English title and skill type, and say for each whether it is already in the tenant's catalog and under which status. Use it to confirm what a set of ids actually is before talking about them or proposing a catalog change. Ids that resolve to no skill are returned in 'unknownIds' rather than failing the call, so name them back to the user. This does not search: resolve a skill NAME with 'search_skills', 'semantic_search_skills' or 'search_skill_catalog' first. Runs one at a time per user: never batch it with another catalog read.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"skillIds":{"type":"array","items":{"type":"string"},"description":"Skill UUIDs, 1 to 50, copied verbatim from an earlier tool result."}},"required":["skillIds"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"skills":{"type":"array","items":{"type":"object","properties":{"inCatalog":{"type":"boolean","description":"True when the skill already appears in the tenant catalog ? pinned, or attributed to a role, level or course and therefore listed on the Skills page with an effective status."},"skillId":{"type":"string"},"skillType":{"type":["string","null"],"description":"hard, soft or language."},"syncStatus":{"type":["string","null"],"description":"The catalog status; null when the skill is not in the catalog."},"syncStatusLabel":{"type":["string","null"],"description":"The product name for syncStatus; null when the skill is not in the catalog."},"synced":{"type":["boolean","null"],"description":"Whether the skill currently syncs to employee profiles under the tenant's synchronization mode."},"title":{"type":"string"}},"required":["inCatalog","skillId","title"]}},"unknownIds":{"description":"Ids that resolve to no skill at all. Never an error ? name them back to the user.","type":"array","items":{"type":"string"}}},"required":["skills"]} -
search_skill_catalogList ONE page of the tenant's skill catalog ? at most 50 skills ? together with the 'total' number of matches. Each row carries the skill UUID, English title, skill type, the catalog status and its product label (Approved / Automatic / Disabled / Review pending), and when the skill joined the catalog. No reference lists, no learning opportunities and no per-person figures: use 'list_skill_references' for which roles and levels use a skill. At least ONE filter is REQUIRED ? the catalog can hold 20 000 skills and cannot be listed in full. When 'hasMore' is true, report the total and the page you read and let the USER ask for the next page or a narrower filter; do not walk the pages yourself. Runs one at a time per user: never batch it with another catalog read.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"searchTerm":{"type":"string","description":"Free-text skill search, at most 100 characters."},"statusFilter":{"type":"array","items":{"type":"string"},"description":"Sync statuses to include: SYNC, SYNC_WHEN_IN_PROFILE, NOT_SYNCED, NEEDS_REVIEW."},"jobArchitectureId":{"type":"string","description":"Job architecture UUID to scope the page to one architecture."},"roleIds":{"type":"array","items":{"type":"string"},"description":"Role item UUIDs (at most 50)."},"levelIds":{"type":"array","items":{"type":"string"},"description":"Level item UUIDs (at most 50)."},"ids":{"type":"array","items":{"type":"string"},"description":"Skill UUIDs to restrict the page to (at most 50)."},"skillTypes":{"type":"array","items":{"type":"string"},"description":"Skill types: hard, soft, language."},"sources":{"type":"array","items":{"type":"string"},"description":"How the skill entered the catalog: attributed or manual."},"page":{"type":"integer","format":"int32","description":"0-based page number (at most 999). Defaults to 0."},"size":{"type":"integer","format":"int32","description":"Rows per page, at most 50. Defaults to 50."},"sort":{"type":"string","description":"Sort as 'addedAt', 'roles', 'levels' or 'skillId', prefixed with '-' for descending. Defaults to newest first."}},"required":[]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"hasMore":{"type":"boolean","description":"True when further pages exist. Report the total and let the user ask for the next page."},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"skills":{"type":"array","items":{"type":"object","properties":{"inCatalogSince":{"type":["string","null"],"description":"ISO-8601 instant the skill entered the catalog, or null when it is only attributed."},"skillId":{"type":"string"},"skillType":{"type":["string","null"],"description":"hard, soft or language."},"syncStatus":{"type":"string","description":"SYNC, SYNC_WHEN_IN_PROFILE, NOT_SYNCED or NEEDS_REVIEW."},"syncStatusLabel":{"type":"string","description":"The name the product shows for syncStatus: Approved, Automatic, Disabled or Review pending."},"title":{"type":"string"}},"required":["skillId","syncStatus","syncStatusLabel","title"]}},"total":{"type":"integer","format":"int32","description":"Total number of skills matching the filters, across all pages."},"totalPages":{"type":"integer","format":"int32"}},"required":["hasMore","page","size","skills","total","totalPages"]} -
set_skill_catalog_statusSet the catalog sync status of 1 to 50 skills. A skill that is not in the catalog yet is ADDED with the status given, which is what the 'Add a new skill' dialog does. Statuses: SYNC (Approved ? always synced), SYNC_WHEN_IN_PROFILE (Automatic ? synced while attributed to a role, level or course), NOT_SYNCED (Disabled ? withdrawn from connected apps), NEEDS_REVIEW (Review pending). Entries are written one at a time and independently: an entry that fails carries a reason in 'failed' while the others still apply, so read BOTH halves of the result before reporting back. Every applied row reports its previous status and whether the skill was newly added.
Input schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string"},"syncStatus":{"type":"string","description":"SYNC, SYNC_WHEN_IN_PROFILE, NOT_SYNCED or NEEDS_REVIEW."}},"required":["skillId","syncStatus"]},"description":"The skills to restatus or add, 1 to 50, each with a skill UUID and a sync status."}},"required":["entries"]}Output schema
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"applied":{"type":"array","items":{"type":"object","properties":{"added":{"type":"boolean","description":"True when the skill did not appear in the catalog before this write, i.e. it was added rather than restatused."},"newStatus":{"type":"string"},"previousStatus":{"type":["string","null"],"description":"The status the skill was listed under before the change; null when it did not appear in the catalog."},"skillId":{"type":"string"},"title":{"type":["string","null"]}},"required":["added","newStatus","skillId"]}},"failed":{"description":"Entries that could not be written. Other entries still went through ? read both halves.","type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"skillId":{"type":"string"}},"required":["reason","skillId"]}}},"required":["applied"]}