Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Inistate MCP Server list entries in the Tasks module"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the Inistate platform — module discovery, entry management, and activity submission.
Variable | Required | Default | Description |
| Yes | — | Bearer token for Inistate API authentication |
| No |
| API base URL |
| No |
| Initial mode: |
| No | — | Set to |
| No | — | Set to |
No clone or build needed — npx will fetch and run the published package on demand:
npx -y inistate-mcpOr install globally:
npm install -g inistate-mcp
inistate-mcpRun the binary in a terminal with no MCP client attached and it walks you through entering your API token and picks the right config file for your client:
npx -y inistate-mcp
# or, explicitly:
npx -y inistate-mcp setupSupported clients: Claude Desktop, Claude Code (global or project-local .mcp.json), Cursor, Windsurf, Codex CLI, VS Code (user profile or workspace .vscode/mcp.json), Cline, Gemini CLI (global or workspace). Pick "Print config only" to get a JSON block to paste anywhere else.
The wizard only runs when stdin is a TTY (i.e., you launched it yourself). When an MCP client spawns the binary via piped stdio, it skips the wizard and runs as a normal MCP server — set INISTATE_MCP_NO_SETUP=1 if you need to force server mode from a terminal.
Add to your claude_desktop_config.json:
{
"mcpServers": {
"inistate": {
"command": "npx",
"args": ["-y", "inistate-mcp"],
"env": {
"INISTATE_API_TOKEN": "your-token-here"
}
}
}
}claude mcp add inistate -e INISTATE_API_TOKEN=your-token-here -- npx -y inistate-mcpgit clone https://github.com/Inistate/inistate-mcp.git
cd inistate-mcp
npm install
npm run buildThen point your MCP client at node /absolute/path/to/inistate-mcp/build/index.js.
Related MCP server: moodle-mcp
Tools marked (configure) are only exposed in configure mode — see Modes. Tools the active backend cannot serve (e.g. scaffold_module on the hosted Platform) stay registered but return a structured capability message instead of failing silently.
Tool | Description |
| List workspaces the user has access to |
| Set the active workspace |
| List all discoverable modules in the workspace |
| Get the canvas schema (basic or extended tier) — available in every mode |
| Get full module definition with stable IDs (round-trippable) (configure) |
| Query entries with filters, sorting, and pagination |
| Read a single entry by ID |
| Get form fields and defaults for an activity |
| Create, edit, delete, or run custom activities |
| Bulk variant — same activity applied to up to 100 entries in one call |
| Get entry audit trail and comments |
| Default upload path — get a presigned S3 URL to PUT file bytes to |
| Confirm a presigned upload completed; returns the File/Image field path |
| Fallback upload via base64/multipart (use only if the presigned flow fails) |
| Download a file (returns pre-signed URL) |
| Generate a scaffolded module template from a description (configure) |
| Validate a module schema before creating or updating (configure) |
| Create a new module with schema (configure) |
| Update an existing module's schema (configure) |
| Draft a module schema from existing data (SQLite, Notion, or Airtable table) (configure) — served by the local runtime (inistate-core); on the hosted Platform backend it returns a capability message pointing to |
| Switch the active mode (runtime / configure / frontend) |
URI | Description |
| List all modules |
| Basic module schema (fields + states) |
| Extended schema with activities and flows |
| Server-enforced |
| Runtime schema — entry/activity/file types and filter operators (default) |
| Module-design schema — write format, field types, colors (configure) |
| FACTS Module Design Guide (configure) |
| REST API reference for hand-written UIs (frontend) |
Prompt | Description |
| Guide an agent through designing a complete workflow module (configure) |
| Guide an agent through executing a specific activity |
| Guide an agent through investigating an entry's state and history |
| Guide an agent through modifying an existing module's schema (configure) |
The server exposes a focused tool/resource surface depending on the active mode, keeping agent context lean. Use switch_mode to change it, or set the initial mode via the INISTATE_MCP_MODE env var (default: configure).
Mode | Surface |
| Entry and activity operations only — querying, reading, submitting, files, history. The leanest surface for using existing modules. |
| Everything in |
| Everything in |
Tools and resources marked (configure) / (frontend) are absent from the tool list in narrower modes — switch modes to reveal them.
list_workspaces → set_workspace — select a workspace (auto-selected when exactly one matches; both return the workspace's module list, so list_modules is only needed to refresh)
get_module_schema — understand a module's fields, states, and activities
get_form — discover required fields before the first submission per (module, activity); reuse its schema for further entries
submit_activity — create or update entries (submit_activities for bulk)
list_entries — query and browse data (use the fields parameter to keep payloads small)
get_entry_history — review entry history
npm run watch # Watch mode for TypeScript compilation
npm run inspector # Test with MCP InspectorSetup
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/or
$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz
Verify
mcp-publisher --helpAuthenticate
mcp-publisher login githubPublish: see below
# Example adding new feature
git checkout -b feat/add-user-tool
# After coding
npx changeset
# Choose:
#
# minor
# Added new user search tool
# Release
npm run release
# This does:
# install dependencies
# test
# bump version + update changelog + sync server.json
# validate MCP server config
# build (via npm prepare hook)
# publish to npm
# publish to MCP registryRun the HTTP transport in production using PM2:
npm install
npm run build
npm run pm2:start
npx pm2 saveEnable startup on reboot:
sudo npx pm2 startup systemd -u ubuntu --hp /home/ubuntu
npx pm2 saveCommon operations:
npm run pm2:restart
npm run pm2:logs
npm run pm2:stopSet required environment variables (INISTATE_API_TOKEN, and optionally INISTATE_API_BASE, INISTATE_WORKSPACE_ID, OAUTH_ISSUER_URL, INISTATE_APP_URL) in your shell, PM2 ecosystem env, or deployment secret manager before starting.
npm testnpm run test:watchTests are in src/ alongside the source files and use Vitest:
File | Type | What it covers |
| Unit tests (76) |
|
| Unit tests (42) |
|
| Unit tests (19) | Tool input-schema shapes and validation |
| Unit tests (9) | Capability gating — tools the active backend cannot serve return a capability message |
| Integration tests (5) | Flagged-response annotation — suppressed transitions are explained ( |
| Integration tests (17) | Spins up the MCP server as a child process and exercises it through the official MCP SDK client — mode-gated tool/resource/prompt discovery, |
Unit tests cover:
Field type and color validation against the schema
State color suggestion logic
Design validation: duplicate names, invalid types/colors/actors, initial state rules, flow integrity, unreachable states, unused activities, AI confidence warnings
Input normalization: field-type, state-color, and industry aliases; parsing states from a description
Workflow design: pattern detection (approval, ticket, pipeline, record list), industry defaults
Integration tests verify (no API token needed):
Mode-gated tool/resource/prompt discovery — runtime mode hides the configure surface, switch_mode reveals and collapses it
design_workflow, validate_design work end-to-end through the MCP protocol
Static resources (inistate://schema/runtime, inistate://design-guide) return valid content
All 4 prompts return correctly templated messages
INISTATE_API_TOKEN=your-token npm run inspectorOpens a browser UI where you can interactively call tools, inspect schemas, and see responses.
Confirm a presigned upload after the PUT to uploadUrl succeeded. The server verifies the object in S3 and returns { url, filename, mimeType, size } — url is the /s/ path usable as a File/Image field value. Returns 400 if the file is not in S3 (ensure the PUT completed first).
| Name | Required | Description | Default |
|---|---|---|---|
| s3Key | Yes | The s3Key returned from request_upload_url. | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by detailing the server-side verification in S3, the exact return fields (url, filename, mimeType, size), and error conditions (400 if file not in S3). This provides rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences that front-load the core action. Every sentence adds value and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description fully explains the return values and error condition. For a simple confirmation step with no nested objects or enums, this is complete and sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description adds no new information about parameters beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: confirming a presigned upload after a successful PUT. It explicitly distinguishes from sibling tools like request_upload_url and upload_file by specifying the exact step in the upload workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use the tool (after the PUT to uploadUrl succeeded) and notes a critical precondition (ensuring the PUT completed first). It does not mention alternative tools or when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new module. Supports workflow modules (states, activities, flows) and record list modules (fields only). Requires Administrator, Consultant, or Workspace Admin role. Validates internally with the same rules as validate_design and returns structured errors without creating anything — a separate validate_design call beforehand is optional. See inistate://schema/configure for field types, color palette, and design rules.
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | Emoji identifier | |
| name | Yes | Module name | |
| flows | No | State transition rules: { from, to, activity } by name. Omit for record list modules. | |
| states | No | Workflow states. Omit for record list modules. | |
| activities | No | Custom activities. Omit for record list modules. | |
| description | No | ||
| information | No | Field definitions. Items matched by id on update enable renaming. | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destroyingHint=false. The description adds that it validates internally and returns structured errors without creating anything if validation fails, plus role requirements, going beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences) with front-loaded purpose, then requirements, validation behavior, and reference. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 8 parameters and nested structures, the description covers essential aspects but does not mention the return value (e.g., created module object) or provide exhaustive parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 88% (high), so baseline is 3. Description adds a reference to external docs for field types and clarifies that certain arrays are omitted for record list modules, but does not deeply explain each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new module and specifies two types (workflow and record list), distinguishing it from siblings like update_module or scaffold_module.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly lists required roles and notes that validate_design is optional, providing good context for when to use, but does not explicitly state when not to use or provide direct alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a scaffolded ModuleSchema template from a natural language description. Use when the user wants to create a new module or workflow.
Design workflow: design_workflow → (complete template) → validate_design → create_module → get_module_schema(tier=extended). Load resources inistate://schema and inistate://design-guide before designing for valid field types, colors, and design rules.
| Name | Required | Description | Default |
|---|---|---|---|
| industry | No | Industry context, free text — mapped to financial_services, healthcare, legal, hr, procurement, it_service, or general (default). Affects audit fields, confidence thresholds, actor suggestions. | |
| description | Yes | Natural language description of the desired workflow. Include: entity type, lifecycle states, activities, who performs each, what data is collected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing resource loading (inistate://schema and inistate://design-guide) and the pipeline nature, which are not conveyed by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundancy: first states purpose, second gives usage trigger, third provides pipeline and prerequisites. Every sentence adds unique value and is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the output type ('scaffolded ModuleSchema template') and its role in a larger workflow. Resource loading and pipeline context provide sufficient completeness for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema descriptions cover both parameters fully (100% coverage), but the tool description enhances them by specifying the industry mapping behavior and providing detailed guidance on what to include in the 'description' parameter, plus resource loading instructions that affect parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it generates a 'scaffolded ModuleSchema template' from natural language, uses a specific verb ('Generate'), and distinguishes from siblings by outlining the workflow pipeline (design_workflow → validate_design → create_module → get_module_schema).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly says 'Use when the user wants to create a new module or workflow' and provides a pipeline for subsequent steps. Lacks explicit 'when not to use' or direct alternatives, but the context is sufficient for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a file by module name. Construct the URL from a File/Image field value: field.path = '/s/{guid}/{fileName}'. Returns a pre-signed S3 URL (1hr TTL).
| Name | Required | Description | Default |
|---|---|---|---|
| guid | Yes | Short ID from the file URL | |
| fileName | Yes | Original filename | |
| moduleName | Yes | Module name (resolved to vectorId internally) | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying that a pre-signed S3 URL with 1hr TTL is returned, which is useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The main purpose is front-loaded, and each sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only file download tool returning a URL, the description is complete. It covers operation, input hints, and output format. No output schema is needed, and the tool is well-documented for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context about how 'guid' and 'fileName' construct the URL path, but does not significantly enhance the parameter meanings beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Download a file by module name' and explains that it returns a pre-signed S3 URL. It distinguishes from sibling tools like upload_file by focusing on download and URL generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage context (construct URL from field.path) but does not explicitly state when to use this tool versus siblings like upload_file or confirm_upload. No direct alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a single entry by its ID. Returns current field values, state, audit metadata, and available activities.
| Name | Required | Description | Default |
|---|---|---|---|
| module | Yes | Module name from list_modules | |
| entryId | Yes | Entry ID | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds value by specifying the exact return data: current field values, state, audit metadata, and available activities. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: one for purpose, one for return. No redundant information. Every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-entry read tool, the description covers purpose and return content. No output schema, but description compensates. Missing error handling or permission details, but adequate given annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description adds no additional meaning beyond the schema, which is acceptable given high coverage, but no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Read), resource (single entry), and method (by its ID). It also lists specific return data, distinguishing it from siblings like list_entries and get_entry_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving a single entry, and sibling names (list_entries, get_entry_history) provide context for alternatives. However, it does not explicitly state when not to use or provide direct compared to similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the audit trail and comments for an entry. Returns chronological list of actions (create, edit, state changes, comments) with field-level change details and AI traceability context.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (0-based, 50 items per page) | |
| module | Yes | Module name from list_modules | |
| entryId | Yes | Entry ID to get history for | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-destructive read-only behavior. Description adds value by specifying output format (chronological list with field-level changes and AI traceability), going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with verb and resource, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes purpose and return content well. However, missing mention of pagination (page parameter) and required parameters (module, entryId). Schema covers them, but description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters with descriptions (100% coverage). Description does not add further parameter details, but baseline 3 is appropriate since schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets audit trail and comments for an entry, mentioning specific return content (chronological actions, field-level changes, AI traceability). Distinguishes from siblings like get_entry, which returns the current entry, not history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly suggests use when audit trail needed, but lacks explicit when-not or alternative tools. Among siblings, get_entry is for current state, but no direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the form fields, current values, and options for a module activity. Call this before the FIRST submit_activity on each (module, activity) pair — the form schema is stable within a session, so reuse it for subsequent entries (per-entry current values come from get_entry/list_entries). User values with no matching field: omit them and note the omission. Never fabricate form data — when a value is uncertain, submit with a lower ai.confidence and state the assumption instead of blocking to ask.
| Name | Required | Description | Default |
|---|---|---|---|
| module | Yes | Module name from list_modules | |
| entryId | No | Entry ID for edit/view/custom activities. Omit for create. | |
| activity | No | Activity name: create, edit, view, or any custom activity name from get_module_schema | create |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety profile. Description adds context about schema stability within a session and the nature of returned data (fields, values, options), going beyond annotations to inform agent behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-loaded with main purpose, followed by concise usage advice and error handling. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description covers purpose, invocation pattern, behavior, and error guidance. It references sibling tools appropriately and provides enough context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant new meaning beyond what the input schema already provides for each parameter, but it reinforces usage patterns related to entryId and activity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the function: retrieving form fields, current values, and options for a module activity. It distinguishes from siblings like get_entry by specifying that per-entry current values come from those tools, providing a clear verb-resource-usage scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises calling before the first submit_activity per (module, activity) pair, notes schema stability and reuse, and explains how to handle unmatched values and uncertainty. This provides comprehensive when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full module definition with stable IDs. The output is round-trippable — modify and send back via update_module. Use this when modifying a module to preserve IDs for renaming.
Modify workflow: list_modules → get_module_canvas → (apply changes) → validate_design → update_module. Load resource inistate://schema before modifying to know valid field types, colors, and actors.
| Name | Required | Description | Default |
|---|---|---|---|
| module | Yes | Module name or numeric ID | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: 'The output is round-trippable — modify and send back via update_module' and instructs to load inistate://schema before modifying. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences covering purpose and workflow, plus a resource instruction. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately conveys that the output is the full module definition and round-trippable. It covers how to use it in a workflow and prerequisites. Could mention return format but not essential for a getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both parameters. The description does not add additional meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the full module definition with stable IDs, using the verb 'get' and specifying 'full module definition'. It distinguishes from siblings like list_modules (which lists) and get_module_schema (likely different scope) by emphasizing round-trippability and the modify workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool when modifying a module to preserve IDs and provides a modify workflow. It gives clear context but does not explicitly state when not to use it, though the workflow implies a sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the canvas schema for a module. Use tier=basic (default) for fields and states only. Use tier=extended to also include activities and flows. Use basic for query operations. Use extended when you need to understand available activities and state transitions.
| Name | Required | Description | Default |
|---|---|---|---|
| tier | No | basic = fields + states. extended = + activities and flows. | basic |
| module | Yes | Module name from list_modules | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent hints. Description adds value by specifying what each tier returns, aiding behavior understanding without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, followed by clear tier guidance. No unnecessary words, perfectly scoped.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given read-only, idempotent nature, complete param descriptions in schema, and absence of output schema, the description fully covers what an agent needs to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description partially repeats schema info but adds usage context for tier, offering marginal additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'get' and resource 'canvas schema for a module'. However, does not explicitly differentiate from sibling tool 'get_module_canvas', which may cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use each tier (basic vs extended) but does not address when to use this tool versus alternatives like get_module_canvas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query entries with filters, sorting, pagination. Filter keys are field display names; values are equality (simple) or operator objects (contains/startsWith/endsWith/min/max/above/below/between/after/before/empty/exists/yes/no/is/not/excludes). Use {or:[…]} for OR; multiple keys are AND-ed. Use 'me' for User-field self-match. See FilterOperators in inistate://schema/runtime for the full set.
Token control: use fields to restrict the returned data to just the columns you need. For modules with many fields this can shrink the response by an order of magnitude. System fields (id, state, audit metadata, etc.) are always returned regardless.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | ||
| fields | No | Field display names (or raw field names) to include in each entry's `data`. Strongly preferred over returning everything when the module has many or large fields — prunes both DB I/O and response tokens. Omit only when you actually need the full row. System fields are always returned. | |
| module | Yes | Module name from list_modules | |
| search | No | Free-text search across document ID, state, and text-like fields; supports * and ? wildcards | |
| sortBy | No | ||
| filters | No | ||
| pageSize | No | Default 50, max 500 | |
| currentPage | No | ||
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. | |
| sortDirection | No | asc |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to repeat those. It adds valuable behavioral details: filtering operators, OR/AND logic, 'me' keyword for user fields, token control via 'fields', and that system fields are always returned. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs: first focuses on filtering core behavior, second on token control. Information is front-loaded (purpose clear immediately). Every sentence adds value, though a tiny bit redundant in the filter explanation. Overall efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description does not describe the return structure (e.g., pagination metadata, entry format). It covers filtering thoroughly but lacks details on response shape. With 10 parameters and nested filters, the missing output context is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%. The description adds significant semantic value for two key parameters: 'filters' (detailed operator explanation) and 'fields' (token control rationale). However, it does not cover undocumented parameters like state, sortBy, currentPage, sortDirection. The added explanation for the covered ones compensates somewhat, but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Query entries with filters, sorting, pagination.' It uses a specific verb (query/list) and identifies the resource (entries). This distinguishes it from siblings like get_entry (single entry) and list_modules (modules).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage context (e.g., token control tips) but does not explicitly state when to use this tool versus alternatives like get_entry for a single entry or other list tools. No 'when not to use' or direct comparisons to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all discoverable modules in the current workspace. set_workspace already returns this list — call this only to refresh it or when operating stateless without set_workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. Description adds context: modules are 'discoverable', and behavior depends on workspace state (stateless vs stateful via set_workspace). No contradiction, and supplements annotations with usage-specific behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second provides usage guidance. Front-loaded and efficient with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 optional parameter, high schema coverage, no output schema, and clear annotations, the description fully covers what an agent needs: purpose, when to use, and parameter semantics. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers workspaceId with description. Description adds conditional semantics: 'Omit if set via env or set_workspace; required in stateless/remote mode', which clarifies when the parameter is needed beyond schema constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List all discoverable modules in the current workspace', specifying verb (list) and resource (modules). It distinguishes from sibling set_workspace by noting that set_workspace already returns this list, avoiding redundancy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'call this only to refresh it or when operating stateless without set_workspace'. Provides clear context and alternative, guiding appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List workspaces the current user has access to. Typically the first call of a session. If exactly one workspace matches, it is selected automatically and its module list is returned — no set_workspace or list_modules needed; otherwise call set_workspace next.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Optional name filter (case-insensitive) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds critical behavioral details: auto-selection of a single matching workspace and return of its module list. This informs the agent of side effects without repetition of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Purpose is front-loaded, and each sentence adds distinct value: purpose, typical usage, and conditional behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and rich annotations, the description covers all necessary context: session-first usage, auto-selection logic, and relationship to siblings. No output schema needed as return value is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the sole optional parameter 'search', and the description does not add additional meaning about it. Baseline 3 is appropriate as the schema already documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists workspaces accessible to the current user, distinguishes it from sibling tools by explaining the automatic selection behavior when only one workspace matches, eliminating the need for set_workspace or list_modules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it is typically the first call of a session and provides clear guidance: if exactly one workspace matches, no further action needed; otherwise call set_workspace next. This effectively tells when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DEFAULT upload path for every file (up to 500MB); upload_file is only the fallback if this flow fails. Flow: 1) call this tool, 2) PUT the raw bytes to uploadUrl with Content-Type exactly matching contentType (S3 rejects mismatches with 403), 3) call confirm_upload({ s3Key }) — its returned path is the File/Image field value for submit_activity. uploadUrl expires in ~1 hour; call again on expiry.
| Name | Required | Description | Default |
|---|---|---|---|
| module | Yes | Module name. Required — scopes the file to the module's storage folder. | |
| fileName | Yes | Original filename including extension (e.g. 'report.pdf') | |
| fileSize | Yes | File size in bytes. Must be > 0 and ≤ 500MB (524288000). | |
| contentType | No | MIME type. Must match the Content-Type header used in the PUT request. | application/octet-stream |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits beyond annotations: file size limit (500MB), upload URL expiration (~1 hour), Content-Type matching requirement with specific 403 error from S3, and the full flow including confirm_upload dependency. Adds significant context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and packed with information in a single paragraph. The numbering of steps aids clarity. Slightly dense but no wasted words; could be improved by breaking into bullet points but not necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, flow with subsequent steps, no output schema), the description is remarkably complete. It covers the entire upload process, expiry, and dependencies. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 5 parameters. The description adds marginal value by framing the purpose of module and contentType in the flow, but does not substantially enhance understanding beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'request upload URL' explicitly states the tool's function. Distinguishes itself from sibling 'upload_file' by stating this is the default path and upload_file is a fallback, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: 'DEFAULT upload path for every file' and when to use alternative: 'upload_file is only the fallback if this flow fails.' Also gives a step-by-step flow. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Not available on this backend — calls return a structured capability_unavailable message. Local-runtime only; use design_workflow to draft a module here.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| state | No | ||
| table | No | ||
| source | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that calls return a 'capability_unavailable' message and that it is local-runtime only. Annotations already declare readOnlyHint=true, etc., but description adds specific error behavior and environment constraint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a clear purpose: stating unavailability and redirecting. No wasted words; highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks details about the tool's actual function (scaffolding from existing data) and parameter roles. While the unavailability message is complete for this backend, a local-runtime agent would be left without guidance. Missing output schema info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about any of the four parameters (name, state, table, source). The agent cannot infer parameter meanings or usage from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description does not explain what the tool does when available; it focuses on unavailability. The title hints at 'scaffold module from existing data' but the description omits this. The agent is told it's unavailable, so purpose is clear in that limited sense.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Not available on this backend' and directs to use 'design_workflow' instead. Provides clear when-not-to-use and an alternative, which is excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the active workspace for the current session. The response includes the workspace's module list — go straight to list_entries / get_form / get_module_schema with those names; list_modules is only needed to refresh. In stateless/remote mode, prefer passing workspaceId directly to each tool instead.
Workflow sequences after workspace is set:
Design: design_workflow → create_module (validates internally)
Execute: list_entries → get_form → submit_activity
Modify: get_module_canvas → validate_design → update_module
Query: list_entries → get_entry / get_entry_history
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | Yes | Workspace ID (or exact name) from list_workspaces |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare idempotentHint=true and destructiveHint=false; description adds behavioral detail: response includes module list. No contradictions, but could mention session state changes more explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with main purpose upfront, followed by workflow sequences. Slightly verbose but each sentence adds value. Good front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param, no output schema), the description is complete: explains effect, response contents, and usage patterns. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of workspaceId. Description adds little beyond schema; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set the active workspace for the current session,' using a specific verb and resource. It distinguishes itself from siblings like list_workspaces and switch_mode by implying context setting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: use this to set workspace, then follow recommended workflows (Design, Execute, etc.). Also advises when to prefer passing workspaceId directly (stateless/remote mode).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk variant of submit_activity: one module + one activity applied to many entries, each item with its own input. Use instead of N sequential submit_activity calls when creating/editing many rows — one tool turn instead of N. A per-item ai wholly replaces the top-level default (no partial merge). Items run sequentially fail-soft on the server: one failure does not abort the rest; per-item outcomes (success, entryId, flagged, validation details) return in results — use clientRef to correlate. Max 100 items; chunk beyond that. Guardrails match submit_activity at batch level: actor='human' rejects the whole batch; actor='hybrid', activity='changeStatus', or any state override (top-level or per-item) requires confirmed: true.
| Name | Required | Description | Default |
|---|---|---|---|
| ai | Yes | Default AI traceability applied to every item that does not specify its own. Same field semantics as submit_activity.ai. | |
| items | Yes | 1-100 items. Each item carries only what differs from the top-level activity. | |
| module | Yes | ||
| activity | No | create | |
| confirmed | No | REQUIRED when the activity is 'changeStatus', any per-item or top-level `state` override is supplied, or the activity's actor is 'hybrid'. Set true ONLY after surfacing the planned bulk action to the user. | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals important behaviors: per-item ai wholly replaces default, fail-soft execution (one failure does not abort rest), per-item outcomes in results, and guardrails at batch level. Annotations already mark destructiveHint=true, which aligns with the write nature, but the description adds significant context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but dense with information. It uses three sentences with clear structure: first defines the tool, second explains fail-soft and results, third covers guardrails and limits. Slightly verbose but efficient given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavioral details (fail-soft, guardrails), and parameter semantics. No output schema, but mentions return of results with per-item outcomes. Could include more on error format or specific field behaviors, but adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has parameter descriptions for many fields (67% coverage). The description adds meaning beyond schema: e.g., 'A per-item ai wholly replaces the top-level default (no partial merge)' and 'use clientRef to correlate' results. This enhances understanding of parameter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is the 'Bulk variant of submit_activity' and describes its function: 'one module + one activity applied to many entries, each item with its own input.' It distinguishes from the sibling submit_activity by noting it is for bulk operations and uses 'Use instead of N sequential submit_activity calls.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: instead of N sequential calls. Also gives limitations: 'Max 100 items; chunk beyond that.' Provides clear guidance on guardrails: 'actor="human" rejects the whole batch; actor="hybrid", activity="changeStatus", or any state override requires confirmed: true.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform an activity on a module entry: standard (create [no entryId], edit, delete, changeStatus, comment, duplicate, manage) or any custom activity from get_module_schema. Call get_form before the first submission per (module, activity); reuse its schema for further entries. The ai object is REQUIRED (reasoning + model + confidence). If confidence < the activity's threshold, the transition is suppressed and the entry is flagged. Server-side guard rules (human/hybrid actor, state-change confirm, confidence-inflation) may block — see inistate://guardrails. Input shapes: ActivitySubmission in inistate://schema/runtime.
| Name | Required | Description | Default |
|---|---|---|---|
| ai | Yes | REQUIRED — AI agent traceability | |
| due | No | ISO 8601 | |
| input | No | Field values keyed by display name. File/Image: {name,path}. Module: {id,value} (both required). User: {id,value,username} (all three required). Plural variants (Users/Modules/Files/Images): arrays of those objects. User/Module shapes are validated pre-flight — bare ids, bare strings, or objects missing any required key will be rejected. | |
| state | No | Target state name | |
| module | Yes | ||
| comment | No | Optional. Add only when it carries information not already in the field values or reasoning. Keep short and precise. | |
| entryId | No | Omit for create | |
| activity | No | create | |
| entryIds | No | For bulk ops | |
| assignees | No | Usernames | |
| confirmed | No | Set true only after explicit user authorization. Required for: changeStatus, state override, hybrid actor, retry after flag. Does not unlock human-actor activities. See inistate://guardrails. | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behaviors beyond annotations: the ai object is required, confidence gating suppresses transitions and flags entries, and server-side guard rules may block. No contradiction with annotations (destructiveHint, readOnlyHint). References external resources for guardrails and input shapes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and workflow, followed by key rules and references. Every sentence adds value, but it is somewhat long and could be trimmed without losing essential information. However, for a complex tool, this level of detail is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, nested objects, and no output schema, the description covers prerequisites (get_form), key input requirements (ai, confirmed), constraints (confidence threshold), and edge cases (guardrails). It references external documentation for full details, which is appropriate. Minor omission: no guidance on error handling or response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83% (good), and the description adds significant value by explaining the ai object requirement, confidence threshold effect, and compound field shapes (User, Module, etc.). It provides context that the schema alone does not, such as the workflow for get_form and guardrails.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Perform an activity on a module entry' and lists standard activities (create, edit, delete, etc.) plus custom ones. It distinguishes itself from siblings like submit_activities (plural, likely bulk) and get_form, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use guidance: call get_form before first submission per (module, activity) and reuse its schema. Warns about server-side guard rules and references inistate://guardrails. However, it does not explicitly contrast with sibling submit_activities for bulk operations, which would strengthen the guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch tool surface. 'configure' (default) = entry CRUD + module design tools and design resources. 'runtime' = entry CRUD plus get_module_schema (available in every mode). 'frontend' = configure + the inistate://frontend-guide resource (REST reference for building Vue/React UIs that call the Inistate API directly) — use it when the user wants a custom UI. The tool/resource list refreshes via list_changed after this call.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Target mode |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as idempotent and non-destructive. The description adds crucial behavioral context: it reveals that the tool/resource list refreshes via 'list_changed' after the call and clarifies what tools/resources are available in each mode. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph with no wasted sentences, but it is slightly verbose. It front-loads the core action and then lists modes and their contents efficiently. Minor room for tightening, but overall strong.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter schema, no output schema, and informative annotations, the description fully covers the tool's behavior: what it does, the effect of each mode, and a side effect (list refresh). It leaves no obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description expands on each enum value beyond the schema's single-word labels. For example, it explains that 'configure' includes entry CRUD and design tools, while 'frontend' adds the inistate://frontend-guide resource. This adds meaningful clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb phrase 'Switch tool surface' and lists the three modes (configure, runtime, frontend) with their distinct feature sets. This clearly differentiates it from sibling tools, which are all separate resource or action tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what each mode enables and explicitly advises using 'frontend' when the user wants a custom UI. It does not explicitly state when not to use the tool, but the mode descriptions provide enough context to select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing module. A section you pass (information/states/activities/flows) replaces that section's entire list — include every existing item you want to keep (matched by id, which enables renaming; omit id to add new items). Omitted sections are left unchanged. Always call get_module_canvas first to obtain the stable module id and item ids. Full-canvas payloads (information included) are validated internally like create_module; for partial payloads, validate the merged canvas with validate_design first.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Module id from get_module_canvas. Identifies which module to update. | |
| icon | No | Emoji identifier | |
| name | No | New module name (for renaming) | |
| flows | No | State transition rules: { from, to, activity } by name. Omit for record list modules. | |
| states | No | Workflow states. Omit for record list modules. | |
| activities | No | Custom activities. Omit for record list modules. | |
| description | No | ||
| information | No | Field definitions. Items matched by id on update enable renaming. | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses behavioral traits beyond annotations: sections are replaced entirely, omitted sections are unchanged, id matching enables renaming, and prerequisite calls are mandatory. No contradiction with annotations (destructiveHint true), and adds context about validation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Efficient four-sentence structure: first sentence states purpose, second explains replacement behavior, third gives prerequisite, fourth provides validation guidance. No redundant information, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, nested objects), the description is thorough: covers purpose, modus operandi, prerequisites, validation, and id handling. No output schema exists, but return value is implied. Contextual completeness is high for the domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (89%), but description adds meaningful context: importance of id from get_module_canvas, replacement semantics for sections, id behavior for renaming, workspaceId omission context. Baseline 3, but description adds significant value beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update an existing module' with specific verb and resource. Distinguishes from siblings like create_module by noting that it modifies an existing module and requires get_module_canvas first. The replacement semantics for sections and prerequisites further differentiate it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Always call get_module_canvas first' and for partial payloads 'validate the merged canvas with validate_design first.' Also explains when to include items (keep) and omit (leave unchanged), and distinguishes validation rules for full vs. partial payloads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FALLBACK ONLY — use request_upload_url + confirm_upload first; call this only after that presigned flow has actually failed. Uploads via base64. Returns { path, filename, mimeType, size } — use path as the File/Image field value in submit_activity. Max 50MB. Blocked: .exe, .bat, .cmd, .dll, .msi.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Base64-encoded file content | |
| name | Yes | Original filename (e.g. 'report.pdf') | |
| module | Yes | Module name. Required — scopes the file to the module's storage folder. | |
| mimeType | No | MIME type of the file | application/octet-stream |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, destructiveHint=false). Description adds substantial behavioral details: base64 upload, return fields, max size, blocked extensions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with fallback warning, no unnecessary text. Every sentence provides essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return values (no output schema needed), constraints, relationship with siblings (request_upload_url, confirm_upload), and parameter context. Fully adequate given tool complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all 5 parameters. The description adds minimal additional meaning beyond the schema, only noting workspaceId omission context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool uploads a file via base64 as a fallback, its return values, and how the output is used. It distinguishes from siblings by specifying it's the fallback when the presigned flow fails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'FALLBACK ONLY — use request_upload_url + confirm_upload first; call this only after that presigned flow has actually failed.' Also provides constraints (max 50MB, blocked file types) and return usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a module schema without submitting anything. create_module (and update_module on full-canvas payloads) runs these same checks internally, so this tool is optional there — use it to iterate on a draft, or before a partial update_module where the merged canvas cannot be checked client-side.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | create = new module (all rules). update = merge (omitted sections acceptable). | create |
| schema | Yes | A complete or partial ModuleSchema object | |
| workspaceId | No | Workspace ID. Omit if set via env or set_workspace; required in stateless/remote mode. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds that it runs the same checks as create_module/update_module and is a non-submitting validation, reinforcing safety. However, it could mention the return value (e.g., validation errors) for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states core purpose, second provides usage guidance. No wasted words, front-loaded, and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple validation tool with good annotations and schema, the description covers the essential purpose and usage context. It could mention the output (e.g., success/error response) but overall is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds limited value beyond schema. It does provide extra guidance on workspaceId (omit if set via env or set_workspace) and reiterates mode semantics, which is helpful but not extensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates a module schema without submitting, and distinguishes it from create_module and update_module by positioning it as a dry-run for iteration. The verb 'validate' and resource 'module schema' are specific and distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool (iterating on a draft, before partial update_module) and when it is optional (create_module already runs these checks). It provides clear alternatives and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.1.1confirm_uploadcreate_moduledesign_workflowdownload_fileget_entryget_entry_historyget_formget_module_canvasget_module_schemalist_entrieslist_moduleslist_workspacesrequest_upload_urlscaffold_moduleset_workspacesubmit_activitiessubmit_activityswitch_modeupdate_moduleupload_filevalidate_designEach tool serves a clearly distinct purpose in workspace management, module design, entry CRUD, file handling, or mode switching. The descriptions provide explicit workflow guidance, eliminating ambiguity between similar operations like submit_activity and submit_activities.
All 21 tool names follow a consistent verb_noun snake_case pattern with verbs like list, get, set, submit, upload, etc. No mixing of conventions, making it easy for an agent to predict tool names.
With 21 tools, the count falls into the borderline range (16-25) per the scoring guidelines. While the server covers a comprehensive domain, the number feels slightly heavy for typical MCP servers, which usually have 3-15 tools.
The tool surface covers the full lifecycle: workspace selection, module creation (design, validate, create), entry CRUD (list, get, form, submit, history), and file upload/download. Minor gaps exist, such as no dedicated tool for deleting entries (handled via submit_activity) and no export functionality, but agents can work around these.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read and author HiveLearn courses, events, quizzes, certificates, resources, leaderboards, tracks.
The Academy curriculum as an offline MCP library. Hosted course connector adds progress.
Read and manage courses, members, orders, events, posts, and settings for Loopwise-powered sites.
Public tools to understand Dynamik, discover datasets, and connect account-scoped capabilities.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Inistate/inistate-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
