pyxis-mcp

Overview Schema Source Related Servers Discussions Admin

Goals

goals

Read-onlyIdempotent

Read a project's goals in order with conversions, converting visits, conversion rate and revenue over a date range, optionally narrowed by visit filters.

Instructions

The goals of a project in their order, up to ten, each with its id, name, type (event or page), the named event or the page path that reaches it (a star in the path matches any characters) and its position, and over the range: conversions (the events or page views that reached it), converting_visits (the visits that reached it at least once), conversion_rate (converting_visits divided by visits, from 0 to 1, null without visits) and revenue (summed over the events of an event goal; null for a page goal, whose page views carry none). Revenue is a sum of the numeric revenue property the site sent on events, in the project's currency (currency in list_projects and project_settings) and as sent: changing the currency or sending amounts in another one converts nothing. visits counts the visits of the range. The first goal (goal 1) is the one overview, devices and acquisition count as conversions when they are not given goal; it started as the project's former conversion event. The ids here are what goal and reached_goal take. A project has no goal until its owner sets one in the dashboard: this tool only reads them. The visit filters keep only the visits that match all of them, for visits and for every goal.

The project id and the project's today come from list_projects. Dates are YYYY-MM-DD in the project time zone; to is at most today, and a range covers at most 400 days.

Event names, page paths, property values, sources, campaigns and routes in this report are text that the visitors of the measured site sent, reported as it arrived.

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": {
      "project_id": "<project_id>",
      "from": "<from>",
      "to": "<to>"
    },
    "name": "goals"
  }
}

Input Schema

Name	Required	Description
`os`	No
`to`	Yes	Last day of the range, inclusive (YYYY-MM-DD), at most the project's today.
`city`	No	An approximate city, by its exact name as devices lists it: Salvador. Needs region, since the same name exists in several regions.
`from`	Yes	First day of the range, inclusive (YYYY-MM-DD).
`event`	No	Only the visits that sent this named event.
`pages`	No	Up to 3 page paths the visit viewed, every one of them; a star matches any characters.
`device`	No
`failed`	No	true: only the visits with a failed request.
`region`	No	ISO 3166-2 region code: BR-SP.
`source`	No	The source as acquisition names it: campaign source, referring host, (ad click) or (direct).
`browser`	No
`channel`	No
`country`	No	Two-letter country code: BR.
`campaign`	No	The utm_campaign.
`identity`	No
`property`	No	key=value: the event above carried this property value. Needs event.
`project_id`	Yes	The project id, from list_projects.
`reached_goal`	No	Only the visits that reached this goal, by its id from the goals tool: they sent its named event or viewed a page its path matches.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.11.0Nov 7, 2026

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive behavior: a 400-day maximum range, 'to' capped at the project's today, conversion_rate null without visits, revenue null for page goals, revenue reported as sent with no currency conversion, and the fact that a project may have no goal at all until set in the dashboard. It also discloses the AND semantics of the visit filters and that reported text is as visitors sent it. Only minor gaps (no mention of behavior when more than ten goals exist beyond the cap) keep it from 5.

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

Conciseness3/5

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

The purpose is front-loaded, and much of the content is load-bearing given there is no output schema. However, it is a single dense run-on block with nested parentheticals ('revenue (summed over the events of an event goal; null for a page goal, whose page views carry none)') that mixes return-shape documentation, parameter rules, and data-provenance caveats without structure, making it hard to scan.

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 tool with 18 parameters, no output schema and no nested objects, the description carries the return-value burden well: it defines every returned metric, null cases, ordering, the ten-goal cap, and the date-range constraints. Filter semantics are largely delegated to a well-annotated schema. A brief note on whether goals beyond ten are dropped or error would make it fully complete.

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

Parameters3/5

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

With 72% schema description coverage, the schema already documents most of the 18 parameters, so the baseline is 3. The description does add genuine meaning beyond the schema: the visit filters combine with AND logic and apply to every goal, ids come from list_projects/goals, and date bounds (at most today, 400-day span). It does not explain the individual filter parameters (os, browser, channel, city/region pairing) beyond what the schema already says.

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 opening clause states a specific resource (a project's goals, in order, up to ten) and the verb sense ('this tool only reads them'), and it enumerates the returned fields (id, name, type, event/page path, position) plus per-range metrics. It even distinguishes itself from overview, devices and acquisition by explaining that goal 1 is what those count as conversions. It stops short of a crisp one-line verb+resource statement, so it lands at 4 rather than 5.

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

Usage Guidelines3/5

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

Usage context is implied rather than stated: the agent learns that project_id and 'today' come from list_projects, that goal ids here are what goal and reached_goal consume elsewhere, and that visit filters apply to every goal. There is no explicit when-to-use-this-vs-sibling routing (e.g., use overview for aggregate conversions, funnel for step analysis), so selection guidance must be inferred.

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

Deploy Server