CrunchJunkie

add_annotation

Add a manual timeline annotation to a client's AI-visibility project — a dated note that pins onto the charts so metric movements come with their explanation. By default the note is internal (team-only); set showInReports:true to make it visible on shared report charts too. Requires MCP write actions; without confirm:true it returns a preview.

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

Input Schema

Name	Required	Description
`date`	No	ISO date the event happened (e.g. "2026-09-01") — backdating is the normal case. Defaults to today.
`text`	Yes	The note (max 500 characters).
`confirm`	No	Set true to apply. Omit for a preview. With confirm:true, also pass the preview's previewToken.
`clientId`	No	Client id (from list_clients) — uses the AI-Visibility project its Overview opens in the app (the newest).
`projectId`	No	AI-visibility project id — alternative to clientId.
`previewToken`	No	With confirm:true: the previewToken from this tool's preview (valid 15 minutes, once, for exactly the previewed arguments).
`showInReports`	No	true → visible on shared report charts (visibility "shared"). Default false → internal, team-only.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 24, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -false
```

First observedOct 19, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description goes substantially further by disclosing the two-phase write flow (a preview is returned unless confirm:true), the permission requirement, and the default-published-visibility of the created note. That is exactly the behavioral context an agent needs before issuing a mutation.

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

Conciseness5/5

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

Three sentences, front-loaded with what the tool creates, then visibility semantics, then the write/preview mechanics. No filler and nothing that could be cut without losing routing information.

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 7-parameter mutation with write semantics and no annotations covering safety, the description covers purpose, permission, defaults and the confirm flow — enough to call it correctly. With no output schema it could still say more about what the preview returns besides the previewToken, and it is silent on error or conflict cases.

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 earns above that by tying showInReports and confirm to their user-visible consequences (shared report charts vs internal; preview vs applied write) rather than just restating field names. It stops at 4 because the date/clientId/projectId targeting options are left entirely to the schema.

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

Purpose5/5

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

States a specific verb and resource ("Add a manual timeline annotation") plus the concrete effect — a dated note pinned onto charts so metric movements carry an explanation. Among siblings that are mostly add_widget/add_market/add_tracking_prompt style mutators, an agent can immediately tell this one produces explanatory timeline notes, not data or layout objects.

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?

Gives clear triggering context (use it when a metric movement needs an explanation attached), states the default visibility (internal/team-only) and how to widen it with showInReports:true. It also flags the prerequisite (requires MCP write actions) and the preview path. It does not name a competing sibling or say when NOT to use it, so it stops short of a 5.

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

All CrunchJunkie tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?