Skip to main content
Glama

Create Exploratory Session

create_session

Creates a new exploratory testing session with a name, mission, tags, assignee, and time estimate, attaching it to a project or release.

Instructions

Create a new exploratory testing session. Requires write permission. mission accepts rich HTML (the high-level charter). assigneeUserId accepts either a User _id ("user_abc...") or an email address — the email is resolved against TestDino users automatically. estimate is in minutes. Findings are not available via MCP — add them in the UI. IMPORTANT: tags must be a JSON array of strings — e.g. ["exploratory","auth"] — NOT the comma-separated form that list_sessions accepts as a filter.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "projectId": "<projectId>",
      "name": "<name>"
    },
    "name": "create_session"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesSession name
tagsNoArray of tag strings, e.g. ["exploratory","auth"]. NOT a comma-separated string.
stateNoWorkflow state (default "new"). Either canonical ("under_review") or display ("Under review") form — server normalizes to lowercase+underscored so UI colors render correctly.
configNo
missionNoRich HTML mission/charter
estimateNoEstimate in minutes
projectIdYesProject ID
releaseIdNoAttach session to this release
attachmentsNoNot supported over MCP: any value is refused with a 400. Tell the user to upload files in the TestDino UI.
environmentNo
sessionTypeNoFree-text type, e.g. "Exploratory", "Regression"
linkedIssuesNoArray of linked-issue objects (same shape as list_sessions returns).
assigneeUserIdNoUser _id ("user_abc...") OR email address — both accepted. Email is looked up server-side.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv2.2.3
    • changedInput schema / properties / attachments / description
      Previous value: -"Array of attachment objects or URLs. Suggestion: attaching files via the hosted MCP can be token-expensive (the base64 payload flows through the LLM context). For lower token usage, consider the TestDino UI or the local `testdino-mcp` npm package."New value: +"Not supported over MCP: any value is refused with a 400. Tell the user to upload files in the TestDino UI."
    • removedInput schema / properties / attachments / items
      Removed value: -{
      -  "additionalProperties": true,
      -  "properties": {
      -    "_id": {
      -      "type": "string"
      -    },
      -    "blobUrl": {
      -      "type": "string"
      -    },
      -    "containerName": {
      -      "type": "string"
      -    },
      -    "fileContent": {
      -      "type": "string"
      -    },
      -    "fileName": {
      -      "type": "string"
      -    },
      -    "fileSize": {
      -      "type": "number"
      -    },
      -    "mimeType": {
      -      "type": "string"
      -    },
      -    "originalFileName": {
      -      "type": "string"
      -    },
      -    "uploadedAt": {
      -      "type": "string"
      -    },
      -    "uploadedBy": {
      -      "type": "string"
      -    },
      -    "url": {
      -      "type": "string"
      -    }
      -  },
      -  "type": "object"
      -}
    • removedInput schema / properties / attachments / type
      Removed value: -"array"
  2. Changed19 schema fields changedv2.2.0
    • addedInput schema / $schema
      Added value: +"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / attachments / description
      Previous value: -"Array of attachment objects or URLs."New value: +"Array of attachment objects or URLs. Suggestion: attaching files via the hosted MCP can be token-expensive (the base64 payload flows through the LLM context). For lower token usage, consider the TestDino UI or the local `testdino-mcp` npm package."
    • addedInput schema / properties / attachments / items / additionalProperties
      Added value: +true
    • addedInput schema / properties / attachments / items / properties
      Added value: +{
      +  "_id": {
      +    "type": "string"
      +  },
      +  "blobUrl": {
      +    "type": "string"
      +  },
      +  "containerName": {
      +    "type": "string"
      +  },
      +  "fileContent": {
      +    "type": "string"
      +  },
      +  "fileName": {
      +    "type": "string"
      +  },
      +  "fileSize": {
      +    "type": "number"
      +  },
      +  "mimeType": {
      +    "type": "string"
      +  },
      +  "originalFileName": {
      +    "type": "string"
      +  },
      +  "uploadedAt": {
      +    "type": "string"
      +  },
      +  "uploadedBy": {
      +    "type": "string"
      +  },
      +  "url": {
      +    "type": "string"
      +  }
      +}
    • addedInput schema / properties / attachments / items / type
      Added value: +"object"
    • changedInput schema / properties / estimate / description
      Previous value: -"Estimate in minutes."New value: +"Estimate in minutes"
    • addedInput schema / properties / estimate / minimum
      Added value: +0
    • changedInput schema / properties / estimate / type
      Previous value: -"number"New value: +"integer"
    • changedInput schema / properties / linkedIssues / description
      Previous value: -"Array of linked-issue objects."New value: +"Array of linked-issue objects (same shape as list_sessions returns)."
    • addedInput schema / properties / linkedIssues / items / additionalProperties
      Added value: +true
    • addedInput schema / properties / linkedIssues / items / properties
      Added value: +{
      +  "displayId": {
      +    "type": "string"
      +  },
      +  "issueType": {
      +    "type": "string"
      +  },
      +  "source": {
      +    "type": "string"
      +  },
      +  "status": {
      +    "type": "string"
      +  },
      +  "title": {
      +    "type": "string"
      +  },
      +  "url": {
      +    "type": "string"
      +  }
      +}
    • addedInput schema / properties / linkedIssues / items / type
      Added value: +"object"
    • changedInput schema / properties / mission / description
      Previous value: -"Rich HTML mission/charter."New value: +"Rich HTML mission/charter"
    • changedInput schema / properties / name / description
      Previous value: -"Session name (required)."New value: +"Session name"
    • changedInput schema / properties / projectId / description
      Previous value: -"Project ID (required)."New value: +"Project ID"
    • changedInput schema / properties / releaseId / description
      Previous value: -"Attach session to this release."New value: +"Attach session to this release"
    • changedInput schema / properties / sessionType / description
      Previous value: -"Free-text type, e.g. 'Exploratory'."New value: +"Free-text type, e.g. \"Exploratory\", \"Regression\""
    • changedInput schema / properties / state / description
      Previous value: -"Workflow state (default 'new'). Either canonical ('under_review') or display ('Under review') form — server normalizes to lowercase+underscored so UI colors render correctly."New value: +"Workflow state (default \"new\"). Either canonical (\"under_review\") or display (\"Under review\") form — server normalizes to lowercase+underscored so UI colors render correctly."
  3. Addedv1.0.10

TDQS

A4/5.0
Behavior4/5

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

Annotations only declare it is a non-read-only, non-destructive, closed-world write. The description adds real behavioral context beyond that: the write-permission requirement, that findings cannot be set through MCP at all, that attachments are rejected with a 400, and that emails are resolved server-side. Return shape is not described, but no output schema exists and the create pattern makes it predictable.

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 core action is front-loaded, followed by a compact sequence of caveats. It is dense but nearly every clause carries operational information; the bolded IMPORTANT tags warning is slightly redundant with the schema's own note but is defensible given how commonly that parameter is malformed.

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 13-parameter create tool with no output schema, the description covers the risky and non-obvious parameters (mission, assigneeUserId, estimate, tags, attachments) plus the permission requirement. A few low-risk parameters (config, environment, sessionType, releaseId, linkedIssues) are left entirely to the schema, which is acceptable since their schema descriptions are adequate or the names are self-explanatory.

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 already 85%, so the baseline is 3; the description still adds value by clarifying that mission takes rich HTML, that estimate is in minutes, and that assigneeUserId accepts either a _id or an email that is resolved server-side. It also warns about the JSON-array tag form versus the comma-separated filter form used elsewhere. Some of this duplicates the schema text, which keeps it from a 5.

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 first sentence gives a specific verb and resource ('Create a new exploratory testing session'), which cleanly separates it from the sibling read/update tools (list_sessions, get_session, update_session). It doesn't explicitly name those siblings as alternatives, so it stops short of a 5.

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?

States the precondition ('Requires write permission') and two important when-not-to-use cases: findings must be added in the UI, and attachments are refused over MCP. It also cross-references list_sessions for the comma-separated tag form, giving a concrete contrast. No explicit guidance on create_session vs update_session, but the create semantics are clear.

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