Skip to main content
Glama
flowsery

flowsery

Official

Track Goal Event

track_goal

Record a single completion of a custom goal, creating it on first use. Attach it to a visitor or session so conversions are counted in analytics; repeat calls count again.

Instructions

Record one completion of a custom goal. The goal is created on first use, so no setup call is needed. Pass visitorUid (the anonymous visitor ID Flowsery assigned on the user's own website) so the completion attaches to that visitor's sessions and source; omit it for an anonymous completion. Each call appends a completion, so repeating it counts the goal twice. Use track_payment for revenue, which records a payment goal on its own. Undo with delete_goals. Requires websiteId or domain with a workspace token.

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": {
      "name": "<name>"
    },
    "name": "track_goal"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesWhich goal was completed, e.g. "newsletter_signup" or "add-to-cart". Reuse the exact name for repeat completions: get_goals, filter_goal and delete_goals all match on it.
domainNoWebsite domain from list_websites (e.g. "example.com"). Alternative to websiteId with a workspace token.
metadataNoExtra context saved with this completion, such as { "plan": "pro", "source": "footer" }. At most 10 keys; omit when there is nothing to add.
timezoneNoThe visitor's IANA timezone (e.g. "Europe/Berlin"). Helps place the visitor in a country when the call comes from a server or proxy.
websiteIdNoWebsite ID from list_websites. Required with a workspace token unless domain is given; ignored with a website key.
sessionUidNoSession ID of the visitor's current session (the _fs_sid value). Ties the completion to that session; without it a server-side call uses the visitor's latest active session.
visitorUidNoAnonymous visitor ID Flowsery assigned on the user's own website (the _fs_vid value). Omit to record an anonymous completion.
workspaceIdNoWorkspace to act in: an id from list_workspaces. Omit to use the default workspace. Use the same workspaceId for every call about the same workspace, since ids from one workspace do not exist in another

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changedv1.5.0
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • changedInput schema / properties / metadata / description
      Previous value: -"Up to 10 custom key-value pairs. Keys: lowercase, max 64 chars. Values: max 255 chars."New value: +"Extra context saved with this completion, such as { \"plan\": \"pro\", \"source\": \"footer\" }. At most 10 keys; omit when there is nothing to add."
    • changedInput schema / properties / name / description
      Previous value: -"Goal name: lowercase letters, numbers, underscores, hyphens only (max 64 chars). E.g. \"newsletter_signup\", \"add-to-cart\""New value: +"Which goal was completed, e.g. \"newsletter_signup\" or \"add-to-cart\". Reuse the exact name for repeat completions: get_goals, filter_goal and delete_goals all match on it."
    • addedInput schema / properties / name / maxLength
      Added value: +64
    • addedInput schema / properties / name / minLength
      Added value: +1
    • addedInput schema / properties / name / pattern
      Added value: +"^[a-z0-9_-]+$"
    • addedInput schema / properties / sessionUid
      Added value: +{
      +  "description": "Session ID of the visitor's current session (the _fs_sid value). Ties the completion to that session; without it a server-side call uses the visitor's latest active session.",
      +  "type": "string"
      +}
    • addedInput schema / properties / timezone
      Added value: +{
      +  "description": "The visitor's IANA timezone (e.g. \"Europe/Berlin\"). Helps place the visitor in a country when the call comes from a server or proxy.",
      +  "type": "string"
      +}
    • changedInput schema / properties / visitorUid / description
      Previous value: -"Visitor UID from the _fs_vid browser cookie of a visitor the tracking script has seen. Omit to record an anonymous completion."New value: +"Anonymous visitor ID Flowsery assigned on the user's own website (the _fs_vid value). Omit to record an anonymous completion."
    • addedInput schema / properties / workspaceId
      Added value: +{
      +  "description": "Workspace to act in: an id from list_workspaces. Omit to use the default workspace. Use the same workspaceId for every call about the same workspace, since ids from one workspace do not exist in another",
      +  "type": "string"
      +}
    • removedOutput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • addedOutput schema / properties / result / additionalProperties
      Added value: +true
    • removedOutput schema / properties / result / description
      Removed value: -"Object with status and data: a confirmation message. The completion itself is written asynchronously and appears in get_goals shortly after."
    • addedOutput schema / properties / result / properties
      Added value: +{
      +  "data": {
      +    "description": "One confirmation message. The completion is written asynchronously and shows in get_goals shortly after",
      +    "items": {
      +      "additionalProperties": true,
      +      "properties": {
      +        "message": {
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "type": "array"
      +  },
      +  "status": {
      +    "description": "\"success\" on every successful call",
      +    "type": "string"
      +  }
      +}
    • addedOutput schema / properties / result / required
      Added value: +[
      +  "status",
      +  "data"
      +]
    • addedOutput schema / properties / result / type
      Added value: +"object"
    • addedOutput schema / required
      Added value: +[
      +  "result"
      +]
  2. Changed5 schema fields changedv0.1.1
    • changedInput schema / properties / domain / description
      Previous value: -"Website domain to query. Required when using a workspace token unless websiteId is provided."New value: +"Website domain from list_websites (e.g. \"example.com\"). Alternative to websiteId with a workspace token."
    • changedInput schema / properties / name / description
      Previous value: -"Goal name — lowercase letters, numbers, underscores, hyphens only (max 64 chars). E.g. \"newsletter_signup\", \"add-to-cart\""New value: +"Goal name: lowercase letters, numbers, underscores, hyphens only (max 64 chars). E.g. \"newsletter_signup\", \"add-to-cart\""
    • changedInput schema / properties / visitorUid / description
      Previous value: -"Visitor UID from the _fs_vid browser cookie"New value: +"Visitor UID from the _fs_vid browser cookie of a visitor the tracking script has seen. Omit to record an anonymous completion."
    • changedInput schema / properties / websiteId / description
      Previous value: -"Website ID to query. Required when using a workspace token unless domain is provided."New value: +"Website ID from list_websites. Required with a workspace token unless domain is given; ignored with a website key."
    • changedOutput schema / properties / result / description
      Previous value: -"Confirmation of the recorded goal event."New value: +"Object with status and data: a confirmation message. The completion itself is written asynchronously and appears in get_goals shortly after."
  3. First observedv0.1.0

TDQS

A4.7/5.0
Behavior4/5

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

Beyond the annotations it discloses that the goal is auto-created on first use, that each call appends so repeats double-count (making the non-idempotent annotation concrete), and that websiteId or domain plus a workspace token is an auth prerequisite. What is not covered is what happens on name-format mismatch or how failures surface, but the added behavioral detail is substantial.

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

Conciseness5/5

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

Five short sentences, front-loaded with purpose, then identity, then side effect, then alternatives and auth. Nothing repeats the title or schema verbatim, and each sentence carries a decision the agent needs.

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

Completeness5/5

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

For an 8-parameter mutation with an output schema and full parameter documentation, the description supplies the missing pieces: auth requirements, auto-creation side effect, append semantics, and the revenue/undo alternatives. Return values need not be described because an output schema exists.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining why visitorUid matters (it ties the completion to that visitor's sessions and source) and reinforcing the workspace-token dependence of websiteId/domain. It does not touch metadata, sessionUid, or timezone, so it is an increment rather than a complete gloss.

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

Purpose5/5

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

Opens with a specific verb and resource: "Record one completion of a custom goal," which tells an agent exactly what is created. It immediately distinguishes itself from track_payment (revenue) and points at delete_goals for undo, so it is separable from its closest siblings without opening any schema.

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

Usage Guidelines5/5

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

Gives explicit routing rules: use track_payment for revenue, undo with delete_goals, pass visitorUid to attach to a visitor or omit it for an anonymous completion. Both the when and the when-not, plus the named alternative, are stated rather than implied.

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