Skip to main content
Glama

PitchSpark: Pre-Seed & Seed Startup Pitches

Investors: save a startup pitch to your PitchSpark saved pitches

pitchspark_watch_pitch_v1
Idempotent

For investors: save one startup pitch to the investor's own PitchSpark saved pitches, to come back to it on pitchspark.io. Use when: an investor wants to save, bookmark, watch or shortlist a pitch found through pitchspark_search_pitches_v1 or pitchspark_get_pitch_v1. Do not use for: contacting the founders (use pitchspark_request_intro_v1); reading pitches; anything the investor has not asked for. Requires a PitchSpark API key (psk_...) from an investor account (self-declared; PitchSpark does not verify accreditation), sent as "Authorization: Bearer psk_..." or in the X-API-Key header; calls without a key, with a submit token (pss_...) or with a key from a non-investor account return UNAUTHORIZED. Saving the same pitch again changes nothing. The founders are not contacted. PitchSpark records the save as interest in the pitch, which can appear in the founders' pitch statistics, where investors are numbered and never named. Returns {"status","pitch_id","next_steps"}: status "watching" (saved now), "already_watching" (it was already saved) or "limit_reached" (a free account already holds 10 saved pitches; nothing is saved; Pro is unlimited). An id that does not exist, a pitch that is not public, and a pitch whose founders have opted out of AI agents all answer NOT_FOUND; a pitch the investor owns or is on the team of is INVALID_ARGUMENT. Limits: 100 calls per API key per UTC day (RATE_LIMITED with retry_after_seconds after that), and 30 tool calls per minute per connection. Uses none of the daily pitch allowance. Calls are logged. Errors are JSON {"error":{"code","message","retry_after_seconds"}}: UNAUTHORIZED, INVALID_ARGUMENT, NOT_FOUND, RATE_LIMITED, INTERNAL.

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

Input Schema

NameRequiredDescriptionDefault
pitch_idYesThe pitch id, copied exactly from the "id" field of a search or details result: 1 to 64 letters, digits, "_" or "-". Ids are not derived from company names; an id that does not exist answers NOT_FOUND.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent only when the call failed (isError true).
statusNo
pitch_idNo
next_stepsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "anyOf": [
      +    {
      +      "required": [
      +        "status",
      +        "pitch_id",
      +        "next_steps"
      +      ]
      +    },
      +    {
      +      "required": [
      +        "error"
      +      ]
      +    }
      +  ],
      +  "properties": {
      +    "error": {
      +      "additionalProperties": false,
      +      "description": "Present only when the call failed (isError true).",
      +      "properties": {
      +        "category": {
      +          "description": "The error class.",
      +          "enum": [
      +            "RATE_LIMITED",
      +            "QUOTA_EXCEEDED",
      +            "UNAUTHORIZED",
      +            "FORBIDDEN",
      +            "VALIDATION_ERROR",
      +            "NOT_FOUND",
      +            "CONFLICT",
      +            "UNKNOWN_TOOL",
      +            "INTERNAL"
      +          ],
      +          "type": "string"
      +        },
      +        "code": {
      +          "description": "Machine-readable error code, e.g. RATE_LIMITED, UNAUTHORIZED, FORBIDDEN, INVALID_ARGUMENT, NOT_FOUND, CONFLICT, PITCH_LIMIT_REACHED, INTERNAL.",
      +          "type": "string"
      +        },
      +        "message": {
      +          "description": "A short human-readable explanation, safe to show the user. Never a stack trace.",
      +          "type": "string"
      +        },
      +        "retry_after_seconds": {
      +          "description": "Seconds to wait before retrying, when waiting helps.",
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "retryable": {
      +          "description": "true when the same call can succeed later without changes.",
      +          "type": "boolean"
      +        }
      +      },
      +      "required": [
      +        "code",
      +        "message"
      +      ],
      +      "type": "object"
      +    },
      +    "next_steps": {
      +      "type": "string"
      +    },
      +    "pitch_id": {
      +      "type": "string"
      +    },
      +    "status": {
      +      "enum": [
      +        "watching",
      +        "already_watching",
      +        "limit_reached"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations, it discloses auth mechanics (psk_ key in Authorization Bearer or X-API-Key), rejects submit tokens and non-investor keys with UNAUTHORIZED, and confirms idempotency semantics in prose ("saving the same pitch again changes nothing") consistent with idempotentHint. It also reveals non-obvious side effects — the save is recorded as interest and can surface in founders' anonymized statistics, founders are not contacted — plus daily and per-minute limits and the full error taxonomy.

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?

Purpose and usage routing are front-loaded, and the following sentences on auth, idempotency, side effects, limits, and errors each carry distinct operational information. It is a dense single block and repeats return-value detail that the output schema already covers, which keeps it from a 5, but there is no filler.

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 a one-parameter mutation with real quota and auth complexity, the definition covers everything needed to call it correctly: credential format, quota consumption ("uses none of the daily pitch allowance"), rate limits with retry_after_seconds, idempotency, privacy side effects, and all error codes. Nothing material is left for the agent to guess.

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% and already documents the id's character set and the NOT_FOUND case, so the baseline is satisfied. The description still adds per-parameter meaning the schema lacks: non-public pitches and founder opt-outs also map to NOT_FOUND, while a pitch the investor owns or is on the team of maps to INVALID_ARGUMENT, which tells the agent how to interpret failures for this argument.

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, resource, and actor: save one startup pitch to the investor's own saved pitches. It scopes the audience ("For investors") and the effect target (the caller's own list on pitchspark.io), which cleanly separates it from search, get, and request_intro siblings.

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?

Explicit "Use when" clause names the triggering intent (save, bookmark, watch, shortlist) and the discovery tools that precede it, while "Do not use for" names the alternative to pick instead for founder contact (pitchspark_request_intro_v1) plus the non-goal of reading pitches. Both the positive and negative conditions are stated, leaving nothing to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources