Skip to main content
Glama
carlosazaustre

Activity Reporting MCP Server

Unified Activity Reporting MCP Server

šŸŽÆ Overview

A unified MCP (Model Context Protocol) server that enables both Google Developer Experts (GDEs) and Microsoft MVPs to report their activities through AI-powered conversational interfaces.

Stop the boring manual data entry! Just talk to Claude and submit your activities naturally - whether it's a YouTube video, blog post, conference talk, or mentoring session.

Supported Programs

  • āœ… Microsoft MVP - Direct API integration with the MVP portal

  • āœ… Google GDE - Integration with Advocu API

  • šŸ”§ Both at once - If you're both an MVP and GDE, use one tool for everything!


Related MCP server: MIST - Model Intelligence System for Tasks

šŸš€ Quick Start

Prerequisites

  • Node.js 18+

  • Claude Desktop

  • At least one access token (MVP or GDE)

Installation

git clone https://github.com/carlosazaustre/advocu-mcp-server.git
cd advocu-mcp-server
npm install
npm run build

Option 2: Global Install

npm install -g advocu-mcp-server

Configuration

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

For Both MVP + GDE:

{
  "mcpServers": {
    "activity-reporting": {
      "command": "node",
      "args": ["/absolute/path/to/advocu-mcp-server/dist/index.js"],
      "env": {
        "MVP_ACCESS_TOKEN": "your_mvp_bearer_token",
        "MVP_USER_PROFILE_ID": "your_mvp_profile_id",
        "ADVOCU_ACCESS_TOKEN": "your_gde_token",
        "DOCS_DIR": "/absolute/path/to/advocu-mcp-server/docs"
      }
    }
  }
}

šŸ“š Important: The DOCS_DIR environment variable is required for documentation tools to work. Set it to the absolute path of the docs directory in your installation.

MVP Only:

{
  "mcpServers": {
    "activity-reporting": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "MVP_ACCESS_TOKEN": "your_mvp_bearer_token",
        "MVP_USER_PROFILE_ID": "your_mvp_profile_id",
        "DOCS_DIR": "/absolute/path/to/advocu-mcp-server/docs"
      }
    }
  }
}

GDE Only:

{
  "mcpServers": {
    "activity-reporting": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "ADVOCU_ACCESS_TOKEN": "your_gde_token",
        "DOCS_DIR": "/absolute/path/to/advocu-mcp-server/docs"
      }
    }
  }
}

Get Your Tokens

Microsoft MVP Token

For Claude Desktop users only (not Claude Code):

npm run capture-mvp-token

This tool will:

  1. Open your default browser to the MVP portal (you should already be logged in)

  2. Show you detailed instructions to capture the token from DevTools

  3. Paste your token when prompted

  4. Automatically update your Claude Desktop config file with the new token

  5. No browser automation detection - uses your real browser session!

Google GDE Token

Get your token from the Advocu Developer Portal.

Restart Claude Desktop

# Quit completely
Cmd+Q  # macOS
Alt+F4 # Windows

# Then reopen Claude Desktop

Look for the šŸ”Ø hammer icon to confirm tools are loaded!


šŸ’¬ Usage Examples

Just talk to Claude naturally! Here are examples:

Documentation Tools

"List available documentation"
"Show me the MVP API reference"
"What documentation is available?"
"Get the error handling documentation"

Microsoft MVP Activities

Submit a Video

"Submit my YouTube video to Microsoft MVP:
- Title: Complete Guide to React Server Components
- Published: October 9, 2025
- URL: https://youtube.com/watch?v=example
- Livestream views: 12,500
- On-demand views: 12,500
- Sessions: 1
- Target audience: Developers, Technical Decision Makers
- My role: Host
- Tech area: Web Development
- Description: A comprehensive tutorial covering React Server Components..."

Submit a Blog Post

"Add my latest blog post to MVP:
- Title: Understanding TypeScript Generics
- Date: 2025-10-01
- URL: https://myblog.com/typescript-generics
- Views: 5,000
- Target audience: Developers
- Role: Author
- Tech area: Developer Tools"

Submit a Conference Talk

"Report my conference presentation to MVP:
- Title: Building Scalable APIs with Node.js
- Date: 2025-09-15
- URL: https://conference.com/my-talk
- In-person attendees: 250
- Sessions: 1
- Target audience: Developers, IT Pros
- Role: Speaker
- Tech area: Cloud & AI"

Google GDE Activities

"Submit my workshop to my GDE profile:
- Title: Advanced React Patterns Workshop
- Type: Workshop
- Date: 2025-08-20
- Format: Hybrid
- Country: United States
- In-person attendees: 50
- Total attendees: 150
- URL: https://workshop.com"
"Create a content creation draft for my Medium article about Next.js 14"
"Report my mentoring session with 3 developers about TypeScript best practices"

šŸ”§ Available Tools

Documentation Tools (2) - Always Available

Tool

Description

Usage

list_documentation

List all available documentation

"List available documentation"

get_documentation

Get a specific documentation file

"Show me the MVP API reference"

Available Documents:

  • api-reference - Complete API documentation for MVP and GDE

  • mvp-api-reference - Detailed MVP API specifications

  • mvp-fixes-changelog - MVP integration fixes history

  • error-handling - Error handling improvements guide

  • mcp-resources - MCP resources usage guide

šŸ“š Note: Documentation tools require DOCS_DIR to be set in your configuration.

Microsoft MVP Tools (3)

Tool

Description

Key Fields

submit_mvp_video

Videos, webinars, livestreams

views, sessions, role, tech area

submit_mvp_blog

Blog posts, articles

views, subscribers, tech area

submit_mvp_speaking

Conference talks, presentations

attendees, sessions, tech area

Google GDE Tools (7)

Tool

Description

submit_gde_content_creation

Articles, videos, podcasts

submit_gde_public_speaking

Talks and presentations

submit_gde_workshop

Training sessions

submit_gde_mentoring

Mentoring activities

submit_gde_product_feedback

Product feedback

submit_gde_googler_interaction

Google employee interactions

submit_gde_story

Success stories


šŸ”„ Token Refresh

Microsoft MVP Token (Expires: Hours/Days)

Your MVP token expires regularly. When you get a 401 error or your token expires:

For Claude Desktop users:

cd /path/to/advocu-mcp-server
npm run capture-mvp-token

What happens:

  1. 🌐 Your default browser opens to the MVP portal

  2. āœ… If you're already logged in, you'll see your account immediately

  3. šŸ” If not logged in, log in with Microsoft (2FA supported)

  4. šŸ› ļø Open DevTools (F12 or Cmd+Option+I)

  5. šŸ“ Navigate to "Add activity" and fill any field

  6. šŸ” In Network tab, find the request to mavenapi-prod.azurewebsites.net

  7. šŸ“‹ Copy the Bearer token from the Authorization header

  8. āŒØļø Paste the token in the terminal

  9. āœ… Your Claude Desktop config file is automatically updated!

  10. šŸ”„ Restart Claude Desktop

Advantages:

  • āœ… Uses your real browser (no automation detection)

  • āœ… Works with 2FA/MFA

  • āœ… Automatically updates your Claude Desktop config file

  • āœ… Clear step-by-step instructions

Google GDE Token (Expires: Less frequently)

Get a fresh token from Advocu when needed and update your config manually.


šŸ“‹ Required Fields Reference

MVP Video Activity

{
  title: string;              // Max 100 chars
  description: string;        // Max 1000 chars
  date: string;              // YYYY-MM-DD
  url: string;               // Video URL
  targetAudience: string[];  // Developer, Student, IT Pro, etc.
  role: string;              // Host, Presenter, etc.
  technologyFocusArea: string;
  liveStreamViews: number;
  onDemandViews: number;
  numberOfSessions: number;  // Default: 1
  isPrivate: boolean;        // Optional
}

MVP Blog Activity

{
  title: string;
  description: string;
  date: string;
  url: string;
  targetAudience: string[];
  role: string;              // Author, Contributor, etc.
  technologyFocusArea: string;
  numberOfViews: number;
  subscriberBase: number;    // Optional
  isPrivate: boolean;        // Optional
}

MVP Speaking Activity

{
  title: string;
  description: string;
  date: string;
  url: string;
  targetAudience: string[];
  role: string;              // Speaker, Panelist, etc.
  technologyFocusArea: string;
  inPersonAttendees: number;
  numberOfSessions: number;
  liveStreamViews: number;   // Optional
  onDemandViews: number;     // Optional
  isPrivate: boolean;        // Optional
}

šŸ—ļø Project Structure

advocu-mcp-server/
ā”œā”€ā”€ src/
│   ā”œā”€ā”€ index.ts                    # Entry point
│   ā”œā”€ā”€ unifiedServer.ts            # Main unified server (MVP + GDE)
│   ā”œā”€ā”€ server.ts                   # Legacy GDE-only server
│   ā”œā”€ā”€ mvpServer.ts                # Standalone MVP server
│   ā”œā”€ā”€ interfaces/                 # Activity interfaces
│   │   ā”œā”€ā”€ ActivityDraftBase.ts    # GDE base interface
│   │   ā”œā”€ā”€ ContentCreationDraft.ts # GDE content creation
│   │   ā”œā”€ā”€ ...                     # Other GDE interfaces
│   │   └── mvp/                    # MVP interfaces
│   │       ā”œā”€ā”€ MVPActivityBase.ts
│   │       ā”œā”€ā”€ MVPVideoActivity.ts
│   │       ā”œā”€ā”€ MVPBlogActivity.ts
│   │       └── MVPSpeakingActivity.ts
│   └── types/                      # Type definitions
│       ā”œā”€ā”€ ContentType.ts          # GDE types
│       ā”œā”€ā”€ ...
│       └── mvp/                    # MVP types
│           ā”œā”€ā”€ MVPActivityType.ts
│           ā”œā”€ā”€ MVPActivityRole.ts
│           └── MVPTargetAudience.ts
ā”œā”€ā”€ scripts/
│   ā”œā”€ā”€ capture-mvp-token.ts        # Token capture tool
│   └── README.md                   # Script documentation
ā”œā”€ā”€ dist/                           # Compiled output
└── docs/                           # šŸ“š Documentation (required for doc tools)
    ā”œā”€ā”€ API.md                      # Complete API reference
    ā”œā”€ā”€ MVP_API_REFERENCE.md        # MVP API specifications
    ā”œā”€ā”€ CHANGELOG_MVP_FIXES.md      # MVP integration changelog
    ā”œā”€ā”€ ERROR_HANDLING_IMPROVEMENTS.md  # Error handling guide
    ā”œā”€ā”€ MCP_RESOURCES.md            # MCP resources guide
    └── RELEASE_NOTES_v0.2.0.md     # Release notes

šŸ› ļø Development

Build

npm run build

Development Mode

npm run dev

Lint and Format

npm run lint
npm run format

Capture MVP Token

npm run capture-mvp-token

šŸ› Troubleshooting

Tools Don't Appear in Claude Desktop

  1. Check config path: Ensure your claude_desktop_config.json is in the right location

  2. Verify build: Run npm run build in the project directory

  3. Check logs: Restart Claude Desktop and check for errors

  4. Verify tokens: Make sure at least one token (MVP or GDE) is configured

401 Unauthorized Error (MVP)

Your token expired. Run:

npm run capture-mvp-token

Follow the instructions to capture a fresh token from DevTools, then restart Claude Desktop.

"At least one of GDE or MVP must be configured"

You need to set either:

  • ADVOCU_ACCESS_TOKEN (for GDE), or

  • MVP_ACCESS_TOKEN + MVP_USER_PROFILE_ID (for MVP)

Both can be set if you're both an MVP and GDE!

Documentation Tools Not Working

If you get errors like "Failed to read resource" or "Documentation not found":

  1. Check DOCS_DIR is set: Make sure you added DOCS_DIR to your Claude Desktop config

  2. Verify the path: The path must be absolute and point to the docs directory

  3. Example: "DOCS_DIR": "/Users/yourname/advocu-mcp-server/docs"

  4. Check directory exists: Run ls "$DOCS_DIR" to verify the directory exists

  5. Restart Claude Desktop: Changes to config require a restart

Example config:

{
  "env": {
    "MVP_ACCESS_TOKEN": "...",
    "DOCS_DIR": "/absolute/path/to/advocu-mcp-server/docs"
  }
}

MVP Submission Fails

  1. Check your profile ID: Make sure MVP_USER_PROFILE_ID is correct

  2. Verify token: Run npm run capture-mvp-token to get a fresh token

  3. Check required fields: All required fields must be provided

  4. Target audience: Must be an array (e.g., ["Developer"])


šŸ”’ Security & Privacy

  • Tokens are stored locally in your Claude Desktop config

  • Never commit tokens to version control

  • captured-api-calls.json is in .gitignore - it contains sensitive data

  • MVP tokens expire regularly for security

  • Tokens are never sent to anyone except the official APIs


šŸ“– API Documentation

Microsoft MVP API

  • Base URL: https://mavenapi-prod.azurewebsites.net/api

  • Endpoint: POST /Activities/

  • Authentication: Bearer token

  • Payload: { "activity": { ...fields } }

Google GDE API (Advocu)

  • Base URL: https://api.advocu.com/personal-api/v1/gde

  • Endpoints: /activity-drafts/{type}

  • Authentication: Bearer token

  • Rate Limit: 30 requests/minute

For detailed field documentation, see docs/API.md.


šŸ¤ Contributing

  1. Fork the project

  2. Create a feature branch: git checkout -b feature/amazing-feature

  3. Commit your changes (use conventional commits)

  4. Push to the branch: git push origin feature/amazing-feature

  5. Open a Pull Request


šŸ“ License

MIT License - see LICENSE file for details.


šŸ™ Acknowledgments


šŸ’” Tips

  • Be specific: The more details you provide to Claude, the better

  • Natural language: Just describe what you did - Claude will structure it

  • Batch submissions: Submit multiple activities in one conversation

  • Check responses: Claude will show you the API response for verification

  • Token expires? Just run npm run capture-mvp-token and paste your new token - takes 30 seconds


Questions or issues? Open an issue on GitHub or check the troubleshooting section.

Want to add more activity types? Check out the code structure and submit a PR! šŸš€

Available Tools

7 tools
submit_content_creationC

Submit a content creation activity draft

ParametersJSON Schema
NameRequiredDescriptionDefault
activityDateYesDate published (YYYY-MM-DD format)
activityUrlYesLink to Content
additionalInfoNoAdditional information (optional)
contentTypeYesContent type
descriptionYesWhat was it about?
metricsYes
privateNoDo you want to make this activity private? (optional)
tagsNoTags (optional)
titleYesWhat was the title?

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. 'Submit a content creation activity draft' implies a write/mutation operation but provides no information about permissions required, whether submissions are final or editable, response format, or any system constraints. Significant behavioral context is missing.

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?

The description is a single, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized and front-loaded with the essential information.

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

Completeness2/5

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

For a mutation tool with 9 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what happens after submission, whether there are validation rules beyond schema constraints, or how this tool differs from sibling submission tools. The high schema coverage helps but doesn't compensate for missing behavioral context.

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?

Schema description coverage is high at 89%, so the schema already documents most parameters well. The description adds no additional parameter information beyond what's in the schema, maintaining the baseline score for good schema coverage.

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 description clearly states the action ('submit') and resource ('content creation activity draft'), making the purpose immediately understandable. It doesn't distinguish from sibling tools, but the specific focus on content creation is evident.

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

Usage Guidelines2/5

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

No guidance is provided about when to use this tool versus the six sibling submission tools (submit_googler_interaction, submit_mentoring, etc.). The description offers no context about appropriate use cases or prerequisites for content creation submissions.

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

submit_googler_interactionC

Submit an interaction with Googlers activity draft

ParametersJSON Schema
NameRequiredDescriptionDefault
activityDateYesInteraction Date (YYYY-MM-DD format)
additionalInfoNoAdditional information (optional)
additionalLinksNoAdditional links (optional)
descriptionYesDescription
formatYesFormat
interactionTypeYesInteraction Type
metricsYes
privateNoDo you want to make this activity private? (optional)
tagsNoTags (optional)
titleYesTitle

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Submit an interaction with Googlers activity draft', which implies a write operation (submission), but it doesn't disclose critical behavioral traits such as permissions required, whether this creates or updates data, potential side effects, or response format. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

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 description is a single, efficient sentence that directly states the tool's action. It's appropriately sized and front-loaded with the key verb 'Submit'. There's no unnecessary elaboration, making it concise, though it could be slightly more informative without losing brevity.

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

Completeness2/5

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

Given the complexity (10 parameters, nested objects, no output schema, and no annotations), the description is incomplete. It doesn't explain the tool's role among siblings, behavioral implications of submission, or what happens after invocation. For a mutation tool with rich input schema but no output or annotations, more context is needed to guide the agent effectively.

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?

Schema description coverage is high at 90%, meaning the schema already documents most parameters well (e.g., 'activityDate' with format, 'format' with enum values). The description adds no additional parameter semantics beyond what's in the schema. With high coverage, the baseline score is 3, as the description doesn't compensate but also doesn't need to heavily given the schema's detail.

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

Purpose3/5

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

The description 'Submit an interaction with Googlers activity draft' states a verb ('Submit') and resource ('interaction with Googlers activity draft'), but it's somewhat vague. It doesn't clearly specify what 'Googlers activity draft' refers to or how this differs from sibling tools like 'submit_product_feedback' or 'submit_mentoring'. The purpose is understandable but lacks precision and sibling differentiation.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'submit_product_feedback' and 'submit_mentoring' available, there's no indication of what specific scenarios warrant this tool over others. Usage is implied only by the tool name and description, with no explicit context or exclusions provided.

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

submit_mentoringC

Submit a mentoring activity draft

ParametersJSON Schema
NameRequiredDescriptionDefault
activityDateYesDate of your mentoring session (YYYY-MM-DD format)
activityUrlYesEvent or relevant link
additionalInfoNoAdditional information (optional)
countryNoCountry (required if eventFormat is In-Person or Hybrid)
descriptionYesWhat was it about?
eventFormatYesSelect event format
inPersonAttendeesNoIn-person attendees (required if eventFormat is Hybrid or In-Person)
metricsYes
privateNoDo you want to make this activity private? (optional)
tagsNoTags (optional)
titleYesWhat was the name of your mentoring session?

TDQS

C2.7/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Submit a mentoring activity draft' implies a write operation but doesn't specify whether this creates a new record, updates an existing one, requires authentication, has side effects, or what happens on success/failure. It lacks details on permissions, rate limits, or the submission process, making it inadequate for a mutation tool.

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?

The description is a single, efficient sentence with no wasted words. It's front-loaded and appropriately sized for the tool's purpose, making it easy to parse quickly.

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

Completeness2/5

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

Given the tool's complexity (11 parameters, mutation operation, no annotations, no output schema), the description is insufficient. It doesn't cover behavioral aspects like what 'submit' entails, error handling, or the expected outcome, leaving significant gaps for an agent to understand and use the tool correctly.

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?

The description adds no parameter-specific information beyond what's in the input schema, which has high schema description coverage (91%). It doesn't explain relationships between parameters (e.g., how 'country' and 'inPersonAttendees' depend on 'eventFormat') or provide additional context, so it meets the baseline for high schema coverage without adding value.

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

Purpose3/5

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

The description 'Submit a mentoring activity draft' clearly states the action (submit) and resource (mentoring activity draft), but it's somewhat vague about what 'submit' entails (e.g., creation, submission for review, or saving). It doesn't explicitly differentiate from sibling tools like 'submit_workshop' or 'submit_public_speaking' beyond mentioning 'mentoring'.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives like 'submit_workshop' or 'submit_public_speaking'. It doesn't mention prerequisites, context for mentoring activities, or any exclusions, leaving the agent to infer usage based on the tool name alone.

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

submit_product_feedbackC

Submit a product feedback activity draft

ParametersJSON Schema
NameRequiredDescriptionDefault
activityDateYesParticipation Date (YYYY-MM-DD format)
additionalInfoNoAdditional information (optional)
contentTypeYesContent type
descriptionYesDescription
metricsYes
privateNoDo you want to make this activity private? (optional)
productDescriptionYesWhat product was it about?
tagsNoTags (optional)
titleYesTitle

TDQS

C2.7/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden for behavioral disclosure. 'Submit a product feedback activity draft' implies a write operation, but it doesn't specify whether this creates a new record, updates an existing one, requires authentication, has side effects, or what happens upon submission. For a mutation tool with zero annotation coverage, this is inadequate.

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?

The description is a single, efficient sentence with zero waste—it directly states the tool's action and resource. It's appropriately sized and front-loaded, making it easy to parse quickly without unnecessary elaboration.

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

Completeness2/5

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

Given the tool's complexity (9 parameters, nested objects, no output schema) and lack of annotations, the description is incomplete. It doesn't address behavioral aspects like mutation effects, error handling, or return values, which are critical for a submission tool. With no output schema and minimal description, the agent lacks sufficient context for reliable use.

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?

Schema description coverage is high at 89%, so the schema already documents most parameters well. The description adds no additional meaning beyond the schema, such as explaining relationships between parameters or usage examples. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but doesn't need to heavily.

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

Purpose3/5

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

The description states the action ('submit') and resource ('product feedback activity draft'), which clarifies the basic purpose. However, it doesn't differentiate this tool from sibling tools like submit_content_creation or submit_story, which likely handle different types of activities. The purpose is clear but lacks sibling distinction.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context (e.g., for product-related feedback vs. other activities), or exclusions. With sibling tools like submit_mentoring and submit_workshop available, this gap leaves the agent uncertain about tool selection.

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

submit_public_speakingC

Submit a public speaking activity draft

ParametersJSON Schema
NameRequiredDescriptionDefault
activityDateYesDate of your talk (YYYY-MM-DD format)
activityUrlYesEvent link or relevant URL
additionalInfoNoAdditional information (optional)
countryNoCountry (required if eventFormat is In-Person or Hybrid)
descriptionYesWhat was it about?
eventFormatYesSelect event format
inPersonAttendeesNoIn-person attendees (required if eventFormat is Hybrid or In-Person)
metricsYes
privateNoDo you want to make this activity private? (optional)
tagsNoTags (optional)
titleYesWhat was the title of your talk?

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden but offers minimal behavioral disclosure. It implies a write operation ('Submit') but doesn't clarify permissions, whether this creates or updates records, error handling, or what happens upon submission. For a mutation tool with 11 parameters, this leaves significant gaps in understanding its behavior.

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?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, with every word contributing to understanding the core function.

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

Completeness2/5

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

For a complex mutation tool with 11 parameters, no annotations, and no output schema, the description is inadequate. It doesn't address behavioral aspects like permissions, side effects, or response format, leaving the agent with insufficient context to use the tool effectively despite the detailed input schema.

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?

Schema description coverage is high at 91%, so the schema already documents most parameters thoroughly. The description adds no additional parameter semantics beyond implying 'draft' submission, which doesn't clarify parameter usage beyond what the schema provides. Baseline 3 is appropriate given the schema does heavy lifting.

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 description clearly states the action ('Submit') and resource ('public speaking activity draft'), providing a specific verb+resource combination. It distinguishes this as a submission tool for public speaking activities, though it doesn't explicitly differentiate from sibling tools like 'submit_workshop' or 'submit_story' beyond the activity type.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites, appropriate contexts, or exclusions, nor does it reference sibling tools like 'submit_workshop' or 'submit_story' to help the agent choose correctly among submission options.

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

submit_storyC

Submit a story activity draft

ParametersJSON Schema
NameRequiredDescriptionDefault
activityDateYesActivity Date (YYYY-MM-DD format)
activityUrlYesLink
additionalInfoNoAdditional information (optional)
descriptionYesDescription
metricsYes
privateNoDo you want to make this activity private? (optional)
significanceTypeYesSignificance type
tagsNoTags (optional)
titleYesTitle of the story
whyIsSignificantYesWhy is it significant

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states 'Submit a story activity draft,' implying a write operation, but doesn't cover permissions, side effects, response format, or error handling. This is inadequate for a tool with 10 parameters and no output schema.

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?

The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, though it could benefit from more detail given the tool's complexity.

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

Completeness2/5

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

For a tool with 10 parameters, nested objects, no annotations, and no output schema, the description is insufficient. It doesn't explain what constitutes a 'story activity,' how submissions are processed, or what happens after submission, leaving significant gaps in understanding.

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?

Schema description coverage is high (90%), so the schema documents most parameters well. The description adds no additional parameter context beyond implying this is for 'story activity' drafts, which doesn't clarify individual parameters. Baseline 3 is appropriate given the schema does the heavy lifting.

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 description clearly states the action ('Submit') and resource ('a story activity draft'), making the purpose understandable. However, it doesn't differentiate this tool from its siblings (like submit_content_creation or submit_public_speaking), which appear to be similar submission tools for different activity types.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus its siblings. The description doesn't mention alternatives, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone.

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

submit_workshopC

Submit a workshop activity draft

ParametersJSON Schema
NameRequiredDescriptionDefault
activityDateYesDate of your workshop (YYYY-MM-DD format)
activityUrlYesWorkshop/event link
additionalInfoNoAdditional information (optional)
countryNoCountry (required if eventFormat is In-Person or Hybrid)
descriptionYesWhat was it about?
eventFormatYesSelect event format
inPersonAttendeesNoIn-person attendees (required if eventFormat is Hybrid or In-Person)
metricsYes
privateNoDo you want to make this activity private? (optional)
tagsNoTags (optional)
titleYesWhat was the name of your workshop session?

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure but provides minimal information. 'Submit a workshop activity draft' implies a write/mutation operation but doesn't clarify permissions needed, whether this creates a new record or updates existing ones, what happens on success/failure, or any rate limits. For a mutation tool with 11 parameters and no annotation coverage, this is inadequate behavioral context.

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?

The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized and front-loaded with the essential information. There's zero waste or redundancy in the phrasing.

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

Completeness2/5

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

For a mutation tool with 11 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what 'submit' means operationally, what happens after submission, whether there's a review process, or what the expected response format might be. The high parameter count and mutation nature demand more contextual information than provided.

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?

Schema description coverage is 91% (high), so the schema already documents most parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema. The baseline score of 3 is appropriate when the schema does the heavy lifting, though the description doesn't compensate for the remaining 9% coverage gap or provide any high-level parameter context.

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 description 'Submit a workshop activity draft' clearly states the verb ('submit') and resource ('workshop activity draft'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling tools like 'submit_content_creation' or 'submit_public_speaking' - all appear to be submission tools for different activity types without clear distinction in the description alone.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus its siblings. While the name suggests it's for workshop activities, there's no explicit comparison to 'submit_content_creation' or 'submit_public_speaking' that might also involve workshops. The description lacks any 'when to use' or 'when not to use' context, nor does it mention prerequisites or alternative tools.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.0.0
    • First observedsubmit_content_creation
    • First observedsubmit_googler_interaction
    • First observedsubmit_mentoring
    • First observedsubmit_product_feedback
    • First observedsubmit_public_speaking
    • First observedsubmit_story
    • First observedsubmit_workshop

TDQS

B3.2/5.0

Scored across 7 tools

Disambiguation5/5

Every tool has a clearly distinct purpose focused on submitting different types of activities (content creation, googler interaction, mentoring, product feedback, public speaking, story, workshop). There is no overlap in functionality - each tool handles a unique activity category, making misselection unlikely.

Naming Consistency5/5

All tools follow a perfect verb_noun pattern with 'submit_' prefix followed by the activity type. The naming is completely consistent across all 7 tools, using snake_case uniformly without any deviations or mixed conventions.

Tool Count5/5

With 7 tools, this is well-scoped for an activity reporting server. Each tool represents a distinct activity category that would realistically need separate submission handling, and the count feels appropriate for the domain without being too sparse or bloated.

Completeness3/5

The server provides comprehensive submission coverage for various activity types, but there are notable gaps in the lifecycle. There are no tools for retrieving, updating, deleting, or listing submitted activities, which limits agents to only creation workflows without the ability to manage existing submissions.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers