Skip to main content
Glama
Unfold-it

Unfold It MCP Server

Official
by Unfold-it
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Unfold It MCP Server

Connect AI assistants to Unfold It -- create goals with AI-generated plans, agent-assisted clarification, plan import with enrichment, individual progress tracking, cohort analytics, and skill assessments.

Built for platforms (academies, LMS tools, coaching apps) that want to use Unfold It as their execution layer. Three autonomy tiers: fully autonomous, semi-auto with review, or import your own steps with AI enrichment. Generate skill assessments with AI-validated MCQs, score them, and automatically create targeted learning paths from the results. Tag goals with custom metadata to track and analyze entire cohorts.

Quick Start

npx @unfoldit/mcp-server

Or install globally:

npm install -g @unfoldit/mcp-server

Related MCP server: Student Progress Tracker MCP Server

Configuration

Set the following environment variables:

Variable

Required

Description

UNFOLD_API_KEY

Yes

Org-scoped API key. Generate at app.unfoldit.com -> Organization -> API Keys

UNFOLD_API_URL

No

API base URL. Defaults to https://api.unfoldit.com

Claude Desktop / Claude Code

Add to your MCP config (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "unfoldit": {
      "command": "npx",
      "args": ["@unfoldit/mcp-server"],
      "env": {
        "UNFOLD_API_KEY": "unfold_sk_..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "unfoldit": {
      "command": "npx",
      "args": ["@unfoldit/mcp-server"],
      "env": {
        "UNFOLD_API_KEY": "unfold_sk_..."
      }
    }
  }
}

API Key Scopes

Your API key needs specific scopes depending on which tools you use:

Scope

Tools

Included by default?

goals:create

create_goal, unfold_goal, submit_clarification, import_plan, delete_goal

Yes

goals:read

get_goal_status, list_goals, get_analytics, get_clarification

Yes

claims:manage

revoke_claim

Yes

assessment:generate

generate_skill_assessment

No -- must be granted explicitly

assessment:score

score_skill_assessment

No -- must be granted explicitly

assessment:read_capabilities

get_assessment_capabilities

No -- must be granted explicitly

Assessment scopes are opt-in. Ask your org owner to enable them in the API Key settings.

Available Tools (13)

create_goal

Create a goal with an AI-generated plan. The agent auto-answers clarification questions using the context you provide. Set auto_respond=false to review agent suggestions before the plan generates. Tag goals with metadata to group and analyse entire cohorts.

Input:

  • title (required) -- Goal title

  • description -- Goal description. More detail produces a better AI plan

  • context -- Rich context for the agent:

    • tech_stack -- e.g. ["Python", "React"]

    • team_size -- e.g. 3

    • timeline -- e.g. "3 months", "Q3 2026"

    • constraints -- e.g. "2 hours per week"

    • experience_level -- e.g. "beginner", "advanced"

    • industry -- e.g. "fintech"

    • additional_notes -- Any other context

  • auto_respond -- true (default): agent answers all questions. false: returns questions with suggestions for review

  • clarification_answers -- Pre-set answers by question ID (agent skips these)

  • goal_context -- "personal" or "professional" (default: "professional")

  • priority -- "low", "medium", or "high" (default: "medium")

  • claim_expires_in_days -- Claim link validity (default: 30)

  • progress_share -- Generate embeddable progress link (default: true)

  • metadata -- Custom key-value tags for analytics grouping, e.g. { cohort: "spring-2026", track: "frontend" }

  • category -- Resource category hint: "learning", "health_adhd", or "general". Auto-detected from goal title and description if not provided. Determines which sources and search strategies are used when attaching resources to substeps.

  • resource_world -- Override resource discovery for this goal:

    • preferred_sources -- Source domains to prioritise, e.g. ["coursera.org", "docs.python.org"]

    • excluded_sources -- Source domains to suppress

    • youtube_playlists -- YouTube playlist IDs to draw resources from

    • lms_search_endpoint -- Custom LMS search endpoint URL

    • content_policies -- { require_verified_sources, show_disclaimer, disclaimer_text }

  • assessment (since v0.7.0) -- Structured assessment input the planner uses to bias step selection. Discriminated by assessment_type:

    • skill_proficiency v1 -- Drop the score_skill_assessment response straight in. The planner prioritises weak facets, compresses strong ones, and anchors steps in work_item_context.

    • clinical_intake v1 -- ADHD / coaching / clinical context. Wire shape is locked; the prompt builder is currently stubbed and returns assessment_type_not_supported until a real partner drives it. Sensitive type -- requires superadmin enablement per org.

    • general v1 -- Catch-all for assessment data that does not fit either typed shape. Treated as soft hints; only constraints honoured as hard limits.

    See GUIDE_ASSESSMENT_TO_PLAN_MCP for the canonical end-to-end walkthrough.

  • request_id (since v0.8.0, optional, idempotency key) -- Within a 5-minute window, two create_goal calls with the same request_id return the SAME goal and claim link instead of creating a new one. See Idempotency below for the rules. Omit to get a fresh goal on every call (default).

Returns: goalId, claimLink, claimToken, progressLink, planGenerationStatus, questions (if auto_respond=false), agentAnswersUsed, idempotentReplay (since v0.8.0), claimStatus (since v0.8.0), warnings (always present, empty when none)

get_goal_status

Get the current status and full step-by-step detail of a goal. Returns individual step data (timestamps, time spent, blocker count, substep progress) when the plan is ready.

Input:

  • goal_id (required) -- The goal ID from create_goal

Returns: Goal status, progress, resourceCategory, steps[] (with per-step detail when plan is ready), metadata, claimCreatedAt, claimedAt, assignedTo, agentAnswersUsed

get_analytics

Aggregated cohort analytics across all API-created goals. Returns KPIs, at-risk learners, a step-level drop-off funnel, and optional breakdowns by metadata dimension or resource type.

Input:

  • group_by -- Metadata key to break down completion rates by (e.g. "track", "cohort", "department")

  • inactive_days -- Flag goals with no step activity in this many days as at-risk (default: 7)

  • include_funnel -- Include step-by-step completion funnel (default: true)

  • include_resources -- Include resource engagement by type and source (default: false)

  • metadata -- Filter to a specific cohort or segment, e.g. { cohort: "spring-2026" }

  • date_from -- ISO date (YYYY-MM-DD). Only include goals created on or after this date

  • date_to -- ISO date (YYYY-MM-DD). Only include goals created on or before this date

Returns:

  • totalGoals, activeGoals, completedGoals, blockedGoals, completionRate, avgDaysToComplete

  • claimsTotal, claimsClaimed, claimsPending, claimsExpired, avgHoursToClaim

  • atRiskCount, atRiskGoals[] (goalId, title, metadata, daysInactive, progressPercent)

  • completionByDimension[] (when group_by is set)

  • stepFunnel[] (stepOrder, stepTitle, completionRate, avgHoursToComplete)

  • resourceEngagement[] (when include_resources=true)

get_clarification

Get pending clarification questions with agent-suggested answers and confidence levels. Use after create_goal with auto_respond=false.

Input:

  • goal_id (required) -- The goal ID from create_goal

Returns: Questions with agentAnswer, agentConfidence (high/medium/low/fallback), agentSource

submit_clarification

Submit answers to clarification questions and trigger plan generation. Provide your own answers for questions you want to override. Agent suggestions are kept for the rest.

Input:

  • goal_id (required) -- The goal ID from create_goal

  • answers -- Your answers keyed by question ID (only include overrides)

  • accept_agent_answers -- Accept agent suggestions for unoverridden questions (default: true)

Returns: goalId, status, planGenerationStatus, agentAnswersUsed

import_plan

Import a pre-formulated plan with steps and substeps. Skips clarification entirely. AI enriches steps with dependencies, critical path, duration estimates, severity, complexity, and quick-win flags.

Input:

  • title (required) -- Goal title

  • description -- Goal description

  • steps (required) -- Array of steps, each with:

    • title (required) -- Step title

    • description -- Step description

    • substeps -- Optional array of substeps with title, description, type (research/work/decision/verification)

  • enrich -- Run AI enrichment (default: true). Set false for 0 credits

  • enrich_options -- Control which enrichment features to run:

    • dependencies, critical_path, duration_estimates, severity, complexity, quick_wins, resources

  • goal_context -- "personal" or "professional" (default: "professional")

  • priority -- "low", "medium", or "high" (default: "medium")

  • claim_expires_in_days -- Claim link validity (default: 30)

  • progress_share -- Generate embeddable progress link (default: true)

  • metadata -- Custom key-value tags for analytics grouping, e.g. { cohort: "spring-2026", track: "backend" }

Returns: goalId, planId, enriched steps[] with metadata, claimLink

list_resource_categories

List available resource categories for goal classification. Returns each category's active providers, content safety policies, and disclaimer text. Use this to build adaptive UIs or to discover which categories are available before creating goals.

Input: None

Returns: Array of categories, each with id, name, description, activeProviders, showDisclaimer, disclaimerText

list_goals

List all goals in your org with optional filters. Use metadata to filter to a cohort, category to segment by goal type, assigned_email to look up a specific learner, or inactive_days to find at-risk goals without pulling full analytics.

Input:

  • status -- Filter by goal status (draft, in_progress, completed, blocked, paused)

  • claim_status -- Filter by claim status (unclaimed, claimed, expired, revoked)

  • category -- Filter by resource category (learning, health_adhd, general). Use this to segment ADHD goals from learning goals in a mixed cohort.

  • metadata -- Filter by metadata tag(s) in "key=value" format, e.g. ["track=frontend", "cohort=spring-2026"]

  • assigned_email -- Return only the goal assigned to this learner email

  • inactive_days -- Return only goals with no step activity in the last N days (1-365)

  • include_steps (since v0.9.1) -- Include per-step details (steps[]) for each goal whose plan is ready. Off by default to keep list payloads lean; set true to render step lists without a get_goal_status call per goal.

  • limit -- Max results (default: 50, max: 100)

  • offset -- Pagination offset

Returns: Array of goal statuses with progress, resourceCategory, metadata, claimCreatedAt, claimedAt. When include_steps=true, each goal whose plan is ready also carries steps[] -- the same per-step shape as get_goal_status (timestamps, time spent, blocker count, substep counts). Goals still generating return steps: null. Steps are not paginated; the full step list is returned per goal.

revoke_claim

Invalidate a claim link so it can no longer be used.

Input:

  • claim_token (required) -- The token from the claim link URL

delete_goal

Delete a goal created via the API. Main use case: after a learner retakes a skill assessment, call create_goal with the new suggested_goal_seed and then delete_goal on the obsolete goal so the dashboard shows the current goal instead of duplicates. Soft delete by default (recoverable); set hard_delete=true to remove the row permanently. Scoped to api-created goals -- cannot delete goals a user created in the webapp UI.

Input:

  • goal_id (required) -- UUID of the goal (the goalId returned by create_goal)

  • hard_delete -- If true, permanently delete the row instead of soft-deleting. Default false.

generate_skill_assessment

Generate a skill-proficiency assessment (MCQs) for a learner. Questions are AI-generated and validated (structural + semantic checks) before being returned. Returns a signed assessment_token that the learner's answers are scored against.

Input:

  • work_item_context (required) -- The work item the learner is preparing for:

    • title (required) -- Work item title

    • description -- Work item description (max 2000 chars)

    • domain_tags -- Tags for question anchoring

  • skill (required) -- Skill to assess (e.g. "Python", "SQL", "Project Management")

  • target_proficiency (required) -- Band the learner should reach: "beginner", "low", "medium", "high"

  • num_questions (required) -- Number of MCQs to generate (3-20)

  • difficulty_mix -- Distribution as {easy, medium, hard} floats summing to 1.0. Default: {easy: 0.2, medium: 0.5, hard: 0.3}

  • band_thresholds -- Custom proficiency band ranges. Default: beginner [0,10], low [11,50], medium [51,85], high [86,100]

  • language -- ISO language code (default: "en")

  • request_id (required) -- Idempotency key. Same request_id returns the same assessment.

Returns: assessment_token, questions[] (stem, options, difficulty, skill_facet), band_map, max_raw_score, target_band, model_meta

Requires scope: assessment:generate

score_skill_assessment

Score a submitted assessment using the signed assessment_token from generate_skill_assessment. Returns the learner's proficiency band, gap vs target, and per-question results. When the learner falls short, includes a suggested_goal_seed you can pass to create_goal to create a targeted learning path.

Input:

  • assessment_token (required) -- The signed token from generate_skill_assessment

  • answers (required) -- Array of {question_id, selected_option_id} (at least one)

  • band_thresholds -- Optional override of proficiency band ranges (defaults to the thresholds embedded in the token)

  • request_id (required) -- Idempotency key

Returns: raw_score, max_raw_score, raw_pct, band, target_band, gap_bands, per_question[], per_facet[] (server-side aggregation per sub-skill with total, correct, raw_pct, classification: weak | strong | mixed), weak_facets[], strong_facets[], facet_coverage (full | partial | difficulty_fallback), recommended_action (none / create_unfold_goal), suggested_goal_seed

Chaining tip: This response is shape-compatible with create_goal's new assessment field (skill_proficiency v1). Drop it in with three header fields added (assessment_type: "skill_proficiency", schema_version: "v1", assessed_at: <ISO timestamp>) and the planner uses it directly. No client-side join logic, no threshold tuning.

Requires scope: assessment:score

get_assessment_capabilities

Get supported parameters for skill assessments. Use this to introspect before calling generate_skill_assessment. No input parameters required.

Returns: schema_version, supported_languages, min_questions, max_questions, supported_proficiency_bands, default_band_thresholds, default_difficulty_mix, open_domain, token_ttl_seconds

Requires scope: assessment:read_capabilities

Idempotency

Available since v0.8.0.

create_goal accepts an optional request_id so a partner can retry safely without producing duplicate goals.

The rules

  1. Scope the key to one logical operation. A "logical operation" is one learner / one enrollment. Construct the key from your own per-learner identifier, for example:

    request_id = "enrollment:42:learner:7"
request_id = "course:python-101:user:abc-123"

  2. Reuse the key on retries, not on new learners. If a network blip or process restart makes you re-send the same call for the same learner, use the same request_id. If you are creating a goal for a DIFFERENT learner, generate a NEW key.

  3. Do NOT derive the key from the body. Two learners enrolled in the same course will produce identical title / description / assessment payloads. If you reuse a body-derived key, the second learner will receive a claim link the first learner already claimed.

  4. Without a request_id, every call creates a fresh goal. This is the default and is always safe.

Cache window

Two calls with the same tenant + request_id within 5 minutes return the same response. After 5 minutes the key falls out of cache and a fresh call creates a new goal. Best-effort across pod restarts and horizontal scaling today; treat the window as a retry helper, not a deduplication guarantee.

Detecting a replay

Two new fields on the response tell you what happened:

  • idempotentReplay: true -- this response was served from cache. A prior call with the same request_id produced this goal.

  • claimStatus: "unclaimed" | "claimed" | "expired" | "revoked" -- current state of the underlying claim token, refreshed from the DB on every replay. null on a fresh create (implicitly "unclaimed").

Branch on this when handling retries:

const result = await create_goal({ title, request_id: enrollmentKey });

if (result.idempotentReplay && result.claimStatus && result.claimStatus !== "unclaimed") {
  // The link was already consumed by the original recipient. Don't
  // forward it again -- prompt the human or open a support ticket
  // depending on your flow.
} else {
  // Safe to forward the claimLink to the learner.
}

How It Works

Tier 1 -- Semi-Auto (Review agent suggestions)

  1. Call create_goal with auto_respond=false and your context

  2. Get back questions with agent-suggested answers and confidence levels

  3. Review suggestions, override any you disagree with

  4. Call submit_clarification to trigger plan generation

  5. Poll get_goal_status until planGenerationStatus is "completed"

Tier 2 -- Full-Auto (Agent handles everything)

  1. Call create_goal with context (auto_respond defaults to true)

  2. Agent answers all clarification questions using your context + user history

  3. Plan generates in the background (15-30s)

  4. Get a claim link immediately -- send it to your user

  5. Poll get_goal_status for completion and agentAnswersUsed transparency

Tier 3 -- Import (Bring your own steps)

  1. Call import_plan with your steps and substeps

  2. AI enriches with dependencies, durations, severity, critical path

  3. Plan is ready immediately (no clarification needed)

  4. Get a claim link and enriched step metadata

Assess-then-Learn (Assessment to goal) [updated v0.7.0]

The canonical chain that turns a scored assessment into a personalised plan, with no client-side join logic:

  1. Call generate_skill_assessment with the skill, target proficiency, and work item context

  2. Present questions to the learner in your UI

  3. Call score_skill_assessment with the token and the learner's answers. Response includes per_facet, weak_facets, strong_facets, facet_coverage (server-side aggregation).

  4. Call create_goal with the score response dropped into the new assessment field (skill_proficiency v1). The planner uses weak/strong facets to bias steps and anchors them in work_item_context.

  5. Send the claim link to the learner.

Full walkthrough with payload examples for skill_proficiency, general, and clinical_intake lives at GUIDE_ASSESSMENT_TO_PLAN_MCP.

Legacy path. Pre-v0.7.0 integrations stuffed the score into additional_context.unfold_assessment per the payload convention. That still works on POST /api/v1/ext/goals for backwards compat; behind the scenes both paths now route through the same prompt-builder registry. New integrations should use the structured assessment field on create_goal.

Example Prompts

"Create a Python certification learning path for a beginner with 2 hours per week for 3 months."

"Import our Jira sprint backlog as a goal with dependencies and time estimates."

"Create a coaching plan for Sarah but let me review the questions before generating the plan."

"Create an ADHD morning routine coaching plan with category health_adhd for a patient who struggles with time blindness."

"List all health_adhd goals in the spring cohort and show me which ones are at risk."

"Show me all goals where the claim link hasn't been used yet."

"What's the progress on goal abc-123? Has the learner started?"

"Generate a Python assessment with 8 questions for someone who needs medium proficiency to work on the ML pipeline."

"Score this assessment and create a goal from the results if the learner didn't reach the target."

Getting an API Key

  1. Go to app.unfoldit.com

  2. Create or switch to your organization

  3. Go to Organization settings

  4. Scroll to API Keys section

  5. Click + Create Key, give it a name, and copy the key

Typed errors and warnings (v0.7.0+)

When a tool fails with a typed error, the response is a structured JSON envelope rather than a stringified message. Branch on error_code:

error_code

When

Notes

models_not_configured

BYO provider role is not configured

Response includes settings_url

provider_unauthorized

BYO provider key rejected

Includes settings_url and switch_to_unfold_ai CTA

provider_quota_exceeded

BYO provider returned quota/billing error

Includes switch_to_unfold_ai CTA

provider_unavailable

BYO provider 5xx or circuit breaker open

Transient; retry later

assessment_type_not_supported

assessment_type recognised but builder not yet wired

Response includes supported list

assessment_type_not_enabled_for_org

Tenant has not opted into this assessment type

Sensitive types (clinical_intake) need superadmin enablement

token_invalid / assessment_expired

Assessment token tampered or past TTL

Regenerate via generate_skill_assessment

idempotency_conflict

Same request_id used with different request body

Pick a new request_id

validation_failed

Generation output failed validation after retry budget

Retry with different request_id

Successful responses on goal creation also carry warnings: ApiWarning[] (always present, empty when none). Known warning codes:

code

When

category_assessment_type_mismatch

category and assessment.assessment_type disagree. Plan was generated using assessment_type.

duplicate_assessment_input

Both structured assessment field and legacy additional_context.unfold_assessment envelope sent. Structured won.

Both branches preserve the structured envelope so AI coding agents can deterministically branch on the error_code or warning code strings. See the versioning policy for stability guarantees on these codes.

Versioning

This package follows semver. Pin a minor version range ("@unfoldit/mcp-server": "^0.8.0") -- you will get fixes and additive features automatically; breaking changes require a major version bump. We support the latest two minor versions; older minors receive security fixes only.

Note: in the pre-1.0 era, each minor bump (e.g. 0.7.x -> 0.8.0) may include additive surface changes such as new optional request fields or new response fields. Existing code keeps working; opt in to new behaviour as you need it.

See GUIDE_MCP_VERSIONING for the full policy. See CHANGELOG.md for what changed in each release.

Learn More

License

MIT

Available Tools

13 tools
create_goalA

Create a goal in your Unfold org with an AI-generated plan.

Returns a one-time claim link to send to the user. When they click it, they auto-join your org, get assigned the goal, and land directly on it with a fully AI-generated plan ready to execute.

The plan generates asynchronously (15-30s). The claim link works immediately. Use get_goal_status to check when planGenerationStatus changes to "completed".

With auto_respond=true (default), the agent answers all clarification questions automatically using the provided context. Set auto_respond=false to get questions back with agent suggestions for client review -- then use submit_clarification to provide your answers.

CHAINING:

  • If you have an assessment scored via score_skill_assessment, drop its response (band, target_band, per_facet, weak_facets, work_item_context) into the 'assessment' field. The planner will prioritise weak facets, skip strong ones, and anchor steps in the work item.

  • Each goal is for one user. Call this once per learner/user.

TYPED ERRORS (branch on error_code):

  • "models_not_configured": tenant's BYO provider has no role configured. Response includes settings_url for the user to fix it.

  • "provider_unauthorized" / "provider_quota_exceeded": BYO provider key rejected. Response may include switch_to_unfold_ai CTA.

  • "assessment_type_not_supported": you sent an assessment whose prompt builder is not yet wired (e.g. clinical_intake before partner integration). Response.details.supported lists what IS wired.

WARNINGS (non-fatal, surfaced in response.warnings):

  • "category_assessment_type_mismatch": category and assessment_type disagree (e.g. learning + clinical_intake). The plan was generated using assessment_type. Set category to align if you want category-aware resource routing.

  • "duplicate_assessment_input": you sent both the structured 'assessment' field and the legacy unfold_assessment envelope inside additional_context. Structured wins.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYesGoal title, e.g. 'AI Fundamentals Learning Path'
contextNoStructured context the planner honours directly (not paraphrased via clarification). Higher-priority than free-form description.
categoryNoGoal category for resource routing. Auto-detected from title if omitted. 'learning' = technical skills, courses, upskilling. 'health_adhd' = ADHD management, executive function, habit building. 'general' = everything else. If you also pass `assessment`, prefer the matching category (learning <-> skill_proficiency, health_adhd <-> clinical_intake) to avoid the category_assessment_type_mismatch warning.
metadataNoCustom key-value tags for filtering and analytics (e.g. {cohort: 'spring-2026', track: 'frontend', department: 'engineering'}). Used in get_analytics to group and filter results.
priorityNomedium
assessmentNoStructured assessment input. Discriminated by assessment_type: - skill_proficiency v1: drop the score_skill_assessment response directly here. The planner uses band/target_band/weak_facets/strong_facets/work_item_context for a targeted plan. - clinical_intake v1: ADHD/coaching/clinical context. Wire shape is locked; the prompt builder is not yet wired (you will get assessment_type_not_supported until a real partner drives it). - general v1: catch-all for assessment data that does not fit either typed shape. Treated as soft hints; `constraints` are the only hard limits.
request_idNoIdempotency key. Within a 5-minute window, two calls with the same request_id return the SAME goal and claim link instead of creating a new one. MUST be unique per logical operation (per learner / per enrollment). Two different learners with identical title/description/assessment MUST use different keys -- if you reuse a key across learners, the second learner receives a claim link the first learner already claimed. Recommended construction: derive from your own enrollment_id, or `${course_id}:${learner_id}`. Omit to get a fresh goal on every call (the default). On a replay, the response's `idempotentReplay` is true and `claimStatus` reflects current DB truth so you can detect a link that was already consumed.
descriptionNoGoal description with context. More detail produces a better AI plan.
auto_respondNotrue = fully autonomous (agent answers all questions). false = returns questions with suggestions for review.
goal_contextNoprofessional
progress_shareNoGenerate an embeddable progress report link
resource_worldNoPer-goal resource config. Overrides org defaults for this goal's resource discovery.
claim_expires_in_daysNoHow many days the claim link stays valid
clarification_answersNoPre-set answers by question ID. Agent skips these questions.

TDQS

A4.6/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full burden. It thoroughly discloses behavioral traits: returns a claim link, async plan generation (15-30s), auto_respond behavior, chaining, typed errors, warnings, and idempotency via request_id. This is comprehensive and exceeds expectations.

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

Conciseness4/5

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

The description is long but well-structured with sections for CHAINING, TYPED ERRORS, and WARNINGS. It front-loads the core purpose. Every sentence adds value, though slight trimming could improve conciseness. Still, it is effectively organized.

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

Completeness5/5

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

Given the complexity (14 parameters, nested objects, no output schema), the description is very complete. It explains the return value (claim link), async behavior, error handling, warnings, and idempotency. Without an output schema, it still provides sufficient response details.

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

Parameters4/5

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

Schema description coverage is 86% (high), so baseline is 3. The description adds significant value beyond the schema, especially for the assessment parameter (explicitly explaining how to use it with chaining and types) and other parameters like auto_respond and request_id. The extra context justifies a 4.

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

Purpose5/5

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

The description clearly states it creates a goal with an AI-generated plan and returns a claim link. It is distinct from sibling tools like get_goal_status and delete_goal. The verb 'create' and resource 'goal' are specific, and the additional feature 'with AI-generated plan' adds clarity.

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

Usage Guidelines4/5

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

The description provides when to use (creating a goal for one user) and chaining information with assessments. It mentions alternatives like submit_clarification and advises calling once per learner. However, it does not explicitly compare to all siblings like import_plan or list_goals.

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

delete_goalA

Delete a goal created via the API.

Use this when regenerating a goal after a learner retakes a skill assessment: call create_goal with the new suggested_goal_seed, then call delete_goal on the obsolete goal so the learner's dashboard shows the current goal instead of duplicates.

Soft delete by default (status='deleted'); the dashboard already filters these out, but a superadmin can restore them. Set hard_delete=true to permanently remove the row and cascade to steps, plans, and share links.

Scoped to api-created goals in your org -- you cannot delete goals a user created in the webapp UI. Calling twice with the same goal_id is safe (soft delete is idempotent).

ParametersJSON Schema
NameRequiredDescriptionDefault
goal_idYesThe UUID of the goal to delete (the goalId returned by create_goal)
hard_deleteNoIf true, permanently delete the row instead of soft-deleting. Default false.

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, fully discloses soft delete default, hard_delete option, scoping to API-created goals, idempotency, and superadmin restoration.

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

Conciseness4/5

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

Well-structured and front-loaded with core action. Each sentence adds value, though could be slightly more concise.

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

Completeness4/5

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

Covers behavior, constraints, and use cases well. Lacks mention of return value, but deletion often returns minimal info. Still fairly complete.

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

Parameters4/5

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

Schema coverage is 100%, baseline 3. Adds context beyond schema: explains goal_id as UUID from create_goal and hard_delete implications.

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

Purpose5/5

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

Clearly states 'Delete a goal created via the API' with specific verb and resource. Distinguishes from siblings like create_goal and list_goals.

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

Usage Guidelines5/5

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

Explicitly describes when to use (regenerating after retake) and when not (goals created in webapp UI). Provides alternatives and notes idempotency.

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

generate_skill_assessmentA

Generate a skill-proficiency assessment (MCQs) for a learner.

You provide a skill, target proficiency, number of questions, and the work item the learner is preparing for. Unfold returns the questions with multiple-choice options, a signed assessment_token, and a proficiency band map. The learner answers in your UI; then call score_skill_assessment with the token and answers.

Questions are AI-generated and validated (structural + semantic) before being returned. The assessment_token is HMAC-signed and tamper-proof; it contains the answer key AND per-question facet labels (since v0.7.0) so scoring is stateless and deterministic, and score returns per-facet aggregation without you doing any client-side joins.

CHAINING:

  • work_item_context is the strongest grounding signal: questions get anchored to it instead of being generic textbook items. Pass title + description whenever you have them.

  • The same work_item_context flows through to score_skill_assessment's suggested_goal_seed, then into create_goal. Keep it consistent across the chain.

TYPED ERRORS (branch on error_code):

  • "models_not_configured" / "provider_unauthorized" / "provider_quota_exceeded" / "provider_unavailable" / "provider_request_invalid": LLM provider issues. Some include settings_url and switch_to_unfold_ai CTA.

  • "validation_failed": generation produced output the validator rejected after retry budget. Retry with a different request_id, or reduce num_questions.

  • "idempotency_conflict": same request_id was used with a different request body; pick a new request_id.

Requires the "assessment:generate" scope on your org API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
skillYesSkill to assess (e.g. 'Python', 'SQL', 'Project Management')
languageNoISO language code (default 'en')
request_idYesClient-supplied idempotency key. Same request_id returns the same assessment.
num_questionsYesNumber of MCQs to generate (3-20)
difficulty_mixNoDifficulty distribution as {easy, medium, hard} floats summing to 1.0. Defaults to {easy: 0.2, medium: 0.5, hard: 0.3}
band_thresholdsNoCustom proficiency band ranges. Defaults: beginner [0,10], low [11,50], medium [51,85], high [86,100]
work_item_contextYesThe work item context to anchor question relevance. Flows through scoring into create_goal; keep it consistent across the chain.
target_proficiencyYesProficiency band the learner should reach

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations provided, the description carries full burden. It discloses that questions are AI-generated and validated, the token is HMAC-signed and tamper-proof, scoring is stateless, and typed errors are returned. This is comprehensive for a mutation tool.

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

Conciseness4/5

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

The description is well-structured with clear sections: purpose, output details, chaining, errors, and scope. It is front-loaded with the core purpose. While somewhat lengthy, each section earns its place and the overall clarity justifies the length.

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

Completeness5/5

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

Given the tool's complexity (8 parameters, nested objects, chaining, error types, scope requirements) and no output schema, the description covers all necessary aspects: input, output format, validation, error handling, chaining with score_skill_assessment, and security requirements. An AI agent has sufficient information to select and invoke the tool correctly.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful extra context for parameters like work_item_context (chaining role, strong grounding), difficulty_mix (defaults), band_thresholds (defaults), and typed errors. It does not add much for simple fields like skill, but overall adds value.

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

Purpose5/5

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

The description clearly states the tool generates a skill-proficiency assessment (MCQs) for a learner, specifying the output and chaining to score_skill_assessment. It distinguishes itself from siblings by naming the downstream tool and emphasizing its role in the assessment pipeline.

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

Usage Guidelines4/5

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

The description provides explicit context for when to use the tool (generating an assessment) and includes chaining guidance, error handling, and scope requirements. However, it does not explicitly state when not to use it or describe alternatives among siblings like get_assessment_capabilities.

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

get_analyticsA

Get aggregated analytics for your organization's goals.

Returns cohort KPIs (total, active, completed, blocked), claim metrics (activation rate, time-to-claim), at-risk learners (inactive for N days), an optional step-level completion funnel, and optional resource engagement breakdown.

Use groupBy to break down completion rates by a metadata dimension (e.g. groupBy="track" shows completion rates for frontend, backend, etc).

Use the metadata filter to narrow the scope to a specific cohort or department (e.g. metadata={cohort: "spring-2026"}).

Examples:

  • "How is the spring 2026 cohort doing?" -> get_analytics({ metadata: { cohort: "spring-2026" } })

  • "Which track has the highest completion rate?" -> get_analytics({ groupBy: "track" })

  • "How many students are at risk this week?" -> get_analytics({ inactiveDays: 7 })

  • "Show me the step-by-step funnel for the frontend track" -> get_analytics({ metadata: { track: "frontend" }, includeFunnel: true })

ParametersJSON Schema
NameRequiredDescriptionDefault
date_toNoISO date (YYYY-MM-DD). Only include goals created on or before this date.
group_byNoMetadata key to group completion rates by (e.g. 'track', 'cohort', 'department'). Returns a completionByDimension breakdown.
metadataNoFilter to a specific cohort or segment by metadata tags (e.g. {cohort: 'spring-2026', track: 'frontend'}).
date_fromNoISO date (YYYY-MM-DD). Only include goals created on or after this date.
inactive_daysNoGoals with no step activity in this many days are flagged as at-risk. Default: 7.
include_funnelNoInclude the step-by-step completion funnel showing where learners drop off.
include_resourcesNoInclude resource engagement breakdown (video vs article, AI vs user-added).

TDQS

A4.2/5.0
Behavior3/5

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

No annotations were provided, so the description bears full responsibility. It implies a read operation but does not explicitly state read-only nature or disclose any side effects, impact on data, or performance considerations.

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

Conciseness4/5

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

The description is well-structured with bullet points and examples, making it easy to scan. It is relatively concise given the amount of information covered, though some repetition could be trimmed.

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

Completeness5/5

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

Despite no output schema, the description thoroughly explains return values (KPIs, at-risk learners, funnels, resource engagement). Given 7 parameters and nested objects, it provides sufficient context for using the tool.

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

Parameters4/5

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

Schema description coverage is 100%; the description adds value by providing examples for groupBy, metadata, and other parameters, clarifying their use in context beyond the schema definitions.

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

Purpose5/5

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

The description clearly states the tool gets aggregated analytics for goals, listing specific KPIs and breakdowns. It distinguishes from siblings like get_goal_status and list_goals by emphasizing aggregation and cohort metrics.

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

Usage Guidelines4/5

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

The description provides examples and explains when to use groupBy and metadata filters, giving clear usage context. However, it does not explicitly state when not to use this tool or contrast it with alternative siblings.

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

get_assessment_capabilitiesA

Get supported parameters for skill assessments.

Returns the schema version, supported languages, min/max question count, proficiency bands, default band thresholds, default difficulty mix, and whether the system is open-domain (accepts any skill) or restricted.

Use this to introspect before calling generate_skill_assessment. No parameters required.

Requires the "assessment:read_capabilities" scope on your org API key.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. Describes return values and required scope. Does not disclose idempotency or lack of side effects, but for a read-only introspection tool, the description is adequate.

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

Conciseness5/5

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

Concise with three front-loaded sentences, each adding value: purpose, specific return fields, and usage guidance.

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

Completeness5/5

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

With no output schema, the description compensates by listing key return fields. Also mentions required scope. Complete for an introspection tool.

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

Parameters4/5

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

No parameters; description states 'No parameters required', which adds clarity. Baseline for zero parameters is 4.

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

Purpose5/5

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

Clearly states it returns supported parameters for skill assessments, listing specific items. Distinguishes from siblings like generate_skill_assessment and score_skill_assessment.

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

Usage Guidelines4/5

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

Explicitly instructs to use this before calling generate_skill_assessment, providing clear context. Does not explicitly mention when not to use, but the directive is sufficient.

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

get_clarificationA

Get pending clarification questions for a goal with agent-suggested answers.

Use this after create_goal with auto_respond=false. Returns the list of clarification questions along with what the agent suggested for each one, including confidence levels and reasoning.

Review the suggestions, then use submit_clarification to accept or override them.

ParametersJSON Schema
NameRequiredDescriptionDefault
goal_idYesThe goal ID returned from create_goal

TDQS

A4.6/5.0
Behavior4/5

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

No annotations provided; description carries full burden. It clearly states the tool retrieves suggestions with confidence and reasoning, implying no destructive behavior, but does not explicitly mark it as read-only.

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

Conciseness5/5

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

Three sentences, each valuable: first defines purpose, second gives usage timing, third explains follow-up action. No wasted words.

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

Completeness4/5

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

Covers purpose, usage context, and follow-up. Lacks detail on output format (e.g., confidence levels) but sufficient for a simple read tool.

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

Parameters4/5

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

Schema coverage is 100% with description for goal_id. Description adds context that goal_id comes from create_goal, enhancing schema meaning.

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

Purpose5/5

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

Specific verb 'Get' with resource 'pending clarification questions for a goal', and distinguishes from siblings like submit_clarification and get_goal_status.

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

Usage Guidelines5/5

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

Explicitly states when to use this tool ('after create_goal with auto_respond=false') and what to do next ('use submit_clarification to accept or override').

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

get_goal_statusA

Get the current status and progress of a goal.

Returns who claimed it, step completion breakdown, plan generation status, and the embeddable progress report link.

Use this to check if plan generation is complete (planGenerationStatus: "completed") or to monitor a learner's progress.

ParametersJSON Schema
NameRequiredDescriptionDefault
goal_idYesThe goal ID returned from create_goal

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries the burden. It discloses the return data (status, progress) and a specific status value to check. It does not detail error behavior or confirm read-only nature, but for a simple retrieval tool, it is fairly transparent.

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

Conciseness5/5

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

The description is extremely concise with four sentences, each adding value: purpose, return fields, and usage guidance. Front-loaded and no wasted words.

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

Completeness4/5

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

Given the tool has one parameter, no output schema, and is straightforward, the description adequately covers purpose, return values, and a usage example. It could include an example or note on errors, but it is complete enough for a simple retrieval.

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

Parameters3/5

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

Only one parameter (`goal_id`) with a schema description that already mentions it comes from `create_goal`. Schema coverage is 100%, so the description adds no new meaning beyond what the schema provides, yielding a baseline score of 3.

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

Purpose4/5

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

The description clearly states the tool returns goal status and progress, listing specific return fields (who claimed, step completion, plan generation status, progress report link). It does not explicitly distinguish from siblings like `list_goals`, but the purpose is unambiguous.

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

Usage Guidelines4/5

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

The description gives a concrete use case: check plan generation completion or monitor progress. It does not mention when not to use it or compare to siblings, but the provided context is helpful.

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

import_planA

Import a pre-formulated plan with steps and substeps into Unfold.

Skips clarification entirely. Use this when you already have a structured plan (e.g. from Jira, Linear, or your own planning tool).

Optionally enriches steps with AI-generated metadata: dependencies between steps, critical path identification, duration estimates, severity/complexity ratings, and quick-win flags. Set enrich=false to skip AI enrichment (0 credits).

Returns the goal with a claim link and the enriched step list.

ParametersJSON Schema
NameRequiredDescriptionDefault
stepsYesList of steps in execution order
titleYesGoal title
enrichNoRun AI enrichment to add dependencies, durations, severity, complexity, critical path, quick wins.
priorityNomedium
descriptionNoGoal description
goal_contextNoprofessional
enrich_optionsNoControl which enrichment features to run
progress_shareNo
claim_expires_in_daysNo

TDQS

A4/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. It discloses optional AI enrichment and credit usage via enrich parameter, and mentions the return value (goal with claim link and enriched step list). However, it does not mention auth requirements, rate limits, or whether it modifies existing data (likely creates new). Adequate but not comprehensive.

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

Conciseness5/5

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

Three focused sentences: main action, context of use, and key options/return. No waste, efficient for AI agent consumption.

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

Completeness4/5

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

Given 9 parameters and nested objects with no output schema, the description covers the essential behavioral context (input, enrichment, output). It does not detail all parameters (e.g., priority, goal_context), but those have schema descriptions. The high-level flow is clear.

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

Parameters3/5

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

Schema coverage is 56%. Description adds meaning about pre-formulated plans and enrichment options, but does not significantly enhance understanding beyond the schema's individual parameter descriptions. For instance, 'enrich' parameter is well-described in schema already. Baseline score applies.

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

Purpose5/5

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

Description clearly states it imports a pre-formulated plan with steps/substeps into Unfold, using the verb 'import' and specifying the resource. It distinguishes from siblings like create_goal by noting 'skips clarification entirely' and that it's for already structured plans from tools like Jira or Linear.

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

Usage Guidelines4/5

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

Explicitly says 'Use this when you already have a structured plan (e.g. from Jira, Linear, or your own planning tool)' and notes it 'skips clarification entirely'. This provides clear context for when to use, though it could explicitly state alternatives (e.g., 'use create_goal for plans needing clarification').

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

list_goalsA

List all goals in your org created via the API.

Filter by goal status (draft, in_progress, completed), claim status (unclaimed, claimed, expired, revoked), metadata tags, assigned learner email, or inactivity (at-risk detection).

Use this to see all learner goals, check progress across a cohort, find unused claim links, or identify learners who have gone inactive.

For aggregate cohort metrics, use get_analytics instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax results to return
offsetNoPagination offset
statusNoFilter by goal status
categoryNoFilter by resource category. Use this to segment ADHD goals from learning goals.
metadataNoFilter by metadata tag(s) in 'key=value' format. Repeatable for AND logic. E.g. ['track=frontend', 'cohort=spring-2026']
claim_statusNoFilter by claim link status
inactive_daysNoReturn only goals with no step activity in the last N days (at-risk detection)
include_stepsNoInclude per-step details (steps[]) for each goal whose plan is ready. Off by default to keep responses lean; set true to render step lists without a get_goal_status call per goal.
assigned_emailNoReturn only the goal assigned to this learner email address

TDQS

A4.4/5.0
Behavior3/5

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

No annotations provided, so description bears full burden. Discloses that include_steps is off by default for performance, implying a behavioral trade-off. Does not mention pagination limits, default ordering, rate limits, or authentication. Adequate but not comprehensive.

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

Conciseness5/5

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

Five sentences, front-loaded with main purpose, then filters, then use cases, then alternative tool. No redundant information, each sentence earns its place.

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

Completeness4/5

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

Covers filtering options, use cases, and alternative tools. Does not describe output format or ordering, but no output schema exists. Adequate for a list endpoint with 9 optional parameters.

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

Parameters4/5

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

Schema coverage is 100% with descriptions for all parameters. Description adds value by explaining 'at-risk detection' for inactive_days, providing example for metadata usage ('track=frontend'), and clarifying benefit of include_steps. Exceeds baseline 3.

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

Purpose5/5

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

Clearly states 'List all goals in your org created via the API.' Identifies the resource (goals) and action (list). Explicitly differentiates from sibling get_analytics by noting 'For aggregate cohort metrics, use get_analytics instead.'

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

Usage Guidelines5/5

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

Provides explicit use cases: 'see all learner goals, check progress across a cohort, find unused claim links, or identify learners who have gone inactive.' Also tells when not to use: 'For aggregate cohort metrics, use get_analytics instead.'

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

list_resource_categoriesA

List available resource categories for goal classification.

Returns the categories you can use in create_goal's category field or as a filter in list_goals. Each category has different resource providers, content safety policies, and plan generation behavior.

For example, "health_adhd" restricts resources to curated clinical sources, excludes medication content, adds disclaimers, and generates shorter substeps with transition rituals. "learning" adds YouTube, GitHub, and Official Docs providers alongside web search.

Use this to build adaptive UIs that show category-specific options to your users.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

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

With no annotations, the description carries the full burden. It discloses that categories affect resource providers, content safety policies, and plan generation behavior. The examples illustrate specific behavioral differences. This is sufficient for a read-only list tool.

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

Conciseness5/5

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

The description is concise and well-structured. The first sentence states the core purpose, followed by usage details, then examples. Every sentence is informative with no redundancy.

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

Completeness5/5

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

Given no parameters and no output schema, the description provides complete context: what the tool returns, how it is used, and example behavior differences. It is fully adequate for an agent to select and invoke the tool.

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

Parameters4/5

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

The tool has no parameters, so the baseline is 4. The description adds value by explaining the meaning and usage of the output (categories), even though it doesn't explain parameter behavior.

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

Purpose5/5

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

The description uses a specific verb 'List' and clearly identifies the resource as 'available resource categories for goal classification'. It distinguishes from siblings like create_goal and list_goals by directly stating the categories are used in those tools. The examples further clarify the purpose.

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

Usage Guidelines5/5

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

The description explicitly states when to use the tool: before create_goal or list_goals to inform category choices, and to build adaptive UIs. It provides context for alternative usage and implies when not needed (if categories are already known).

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

revoke_claimA

Invalidate a claim link so it can no longer be used.

Does not remove access from a user who already claimed the goal. Use this if a link was sent to the wrong person or needs to be regenerated.

ParametersJSON Schema
NameRequiredDescriptionDefault
claim_tokenYesThe claim token from the claim link URL (the part after /claim/)

TDQS

A4.4/5.0
Behavior4/5

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

Given no annotations, the description carries the full burden. It discloses that the tool invalidates a link and does not affect existing claims. However, it lacks details on idempotency, error behavior, or authentication requirements, which would improve transparency.

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

Conciseness5/5

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

The description is extremely concise (two sentences) and effectively front-loaded with the action. Every sentence adds value without redundancy, making it easy for an agent to quickly understand.

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

Completeness4/5

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

For a simple tool with one parameter and no output schema, the description is fairly complete. It covers purpose, usage, and a key behavioral caveat. It lacks explicit mention of return values or error cases, but these are less critical given the tool's simplicity.

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

Parameters3/5

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

Schema coverage is 100% with a clear description for the only parameter (claim_token). The main description does not add additional parameter context beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

Purpose5/5

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

The description clearly states the action 'Invalidate a claim link' and the resource, distinguishing it from sibling tools that focus on goals and assessments. It specifies the exact effect and what it does not do, leaving no ambiguity about its purpose.

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

Usage Guidelines5/5

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

The description provides explicit guidance on when to use this tool ('if a link was sent to the wrong person or needs to be regenerated') and clarifies what it does not do ('Does not remove access from a user who already claimed the goal'), which helps the agent avoid misuse.

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

score_skill_assessmentA

Score a skill assessment using answers and the assessment_token from generate_skill_assessment.

Returns the raw score, percentage, proficiency band, gap vs target, and per-question results. When the learner falls short of the target band, includes a suggested_goal_seed you can pass to create_goal.

PER-FACET AGGREGATION (since v0.7.0): Response also includes per_facet (one entry per sub-skill with total, correct, raw_pct, classification) and shortlists weak_facets + strong_facets. Aggregation is computed server-side from facets embedded in the signed token, so partners do not write join logic. The facet_coverage field tells you whether facet labels are real ("full"), partially synthetic ("partial"), or entirely difficulty-bucket fallbacks ("difficulty_fallback") -- soften "weak in X" UI framing when coverage is not "full".

CHAINING into create_goal: The shape of this response is purpose-built to drop straight into create_goal's 'assessment' field (as a skill_proficiency v1 variant):

  • band -> achieved_band

  • target_band -> target_band

  • raw_pct, gap_bands -> same names

  • weak_facets, strong_facets -> same names

  • work_item_context comes from your original generate_skill_assessment call Add assessment_type: "skill_proficiency", schema_version: "v1", and assessed_at (ISO 8601 current time) headers.

Scoring is stateless and deterministic: the signed assessment_token contains the answer key. Tampered or expired tokens are rejected. Same request_id returns the same result (idempotent).

TYPED ERRORS (branch on error_code):

  • "token_invalid": signature mismatch or malformed token. Regenerate via generate_skill_assessment.

  • "assessment_expired": token past TTL. Regenerate.

  • "idempotency_conflict": same request_id was used with different answers; pick a new request_id.

Requires the "assessment:score" scope on your org API key.

ParametersJSON Schema
NameRequiredDescriptionDefault
answersYesLearner's answers (at least one)
request_idYesClient-supplied idempotency key
band_thresholdsNoOptional override of proficiency band ranges (defaults to the thresholds embedded in the token)
assessment_tokenYesThe signed token from generate_skill_assessment

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations, the description fully discloses behavior: stateless and deterministic scoring, token contains answer key, tampered/expired tokens are rejected, idempotent via request_id. It also mentions facet aggregation, coverage field, error codes, and required scope.

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

Conciseness4/5

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

The description is well-structured with sections (chaining, errors) and front-loads the main purpose. It is detailed but not verbose; every section adds value. A slightly more condensed version could be possible, but current structure is good.

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

Completeness5/5

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

Given the tool's complexity (4 params, nested objects, no output schema), the description covers everything needed: return values, error handling, chaining instructions, facet aggregation, and required scope. It is fully complete.

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

Parameters3/5

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond schema: it explains assessment_token's source and chaining, but does not elaborate on parameters beyond what the schema already provides.

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

Purpose5/5

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

The description clearly states the tool's purpose: scoring a skill assessment using answers and the assessment_token from generate_skill_assessment. It specifies the resource (skill assessment) and action (score), and distinguishes it from siblings like generate_skill_assessment and create_goal.

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

Usage Guidelines4/5

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

The description provides explicit usage context: it must follow generate_skill_assessment, explains chaining into create_goal, and describes stateless, deterministic behavior. It does not explicitly exclude alternative tools, but the context is clear enough.

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

submit_clarificationA

Submit answers to clarification questions and trigger plan generation.

Use after create_goal with auto_respond=false. Provide your own answers for questions you want to override. Set accept_agent_answers=true (default) to keep the agent's suggestions for all questions you did not explicitly answer.

After submission, the plan generates asynchronously. Use get_goal_status to check when planGenerationStatus changes to "completed".

ParametersJSON Schema
NameRequiredDescriptionDefault
answersNoYour answers keyed by question ID. Only include questions you want to override.
goal_idYesThe goal ID from create_goal
accept_agent_answersNoAccept agent-suggested answers for questions not in your answers.

TDQS

A4.7/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. It discloses asynchronous plan generation and how to monitor status. Could mention if answers are mutable or if re-submission is allowed, but overall good.

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

Conciseness5/5

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

Three concise paragraphs. First sentence immediately conveys purpose. Every sentence adds value without redundancy.

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

Completeness5/5

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

Covers the full workflow: prerequisite (create_goal), parameter usage, async behavior, and follow-up check. No output schema needed for this tool.

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

Parameters4/5

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

Schema coverage is 100%. Description adds meaning: explains answers are for overriding, accept_agent_answers keeps suggestions, goal_id comes from create_goal. Adds context beyond schema.

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

Purpose5/5

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

The description clearly states 'Submit answers to clarification questions and trigger plan generation', using a specific verb and resource. It distinguishes from sibling tools like get_clarification and create_goal.

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

Usage Guidelines5/5

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

Explicitly says 'Use after create_goal with auto_respond=false' and explains when to use accept_agent_answers. Also provides follow-up steps using get_goal_status.

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

Tool Schema Changelog

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

  1. 13 tool updatesv0.9.1
    • First observedcreate_goal
    • First observeddelete_goal
    • First observedgenerate_skill_assessment
    • First observedget_analytics
    • First observedget_assessment_capabilities
    • First observedget_clarification
    • First observedget_goal_status
    • First observedimport_plan
    • First observedlist_goals
    • First observedlist_resource_categories
    • First observedrevoke_claim
    • First observedscore_skill_assessment
    • First observedsubmit_clarification
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose, covering goal CRUD, claim management, clarification, plan import, analytics, and assessment lifecycle. No overlap in functionality, and descriptions make boundaries explicit.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case (e.g., create_goal, list_goals, generate_skill_assessment). No deviations or mixed conventions.

Tool Count5/5

With 13 tools, the set is well-scoped for the domain. It provides comprehensive operations without being bloated or sparse, fitting the typical 3-15 range.

Completeness5/5

The tool surface covers the full lifecycle: goal creation, status tracking, listing, deletion; claim management; clarification handling; plan import; assessment generation, scoring, and capabilities; analytics; and resource categories. No obvious gaps for the domain.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Unfold-it/unfoldit-mcp-server'

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