Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Neptime MCP Server show me the top 10 trending videos"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for Neptime.io video platform API integration.
This MCP server provides 39 tools for interacting with the Neptime.io API:
List, search, and get trending videos
Get video details
Update and delete your videos
Rate videos (like/dislike)
Upload videos through Neptime.io's live multipart upload endpoint
Supports local file paths or base64-encoded video bytes
Optional thumbnail, category, privacy, age restriction, and short-form flags
Get channel information
Get channel videos
Subscribe/unsubscribe from channels
View your subscriptions
Create, update, and delete playlists
Add/remove videos from playlists
View playlist details
Get video comments
Post comments on videos
Get and post article comments when supported by the Neptime API
Delete your comments
Rate comments
List and get articles
Create, update, and delete articles
View watch history
Clear watch history
Manage watch later list
Get all categories
Get videos by category
Report videos for violations
Related MCP server: Kaltura MCP Server
npm install -g neptime-mcp-serverOr run directly with npx:
npx neptime-mcp-serverCreate a new API key with the required scopes
Copy the API key
Set the NEPTIME_API_KEY environment variable:
export NEPTIME_API_KEY="your-api-key-here"Add to your MCP client configuration (e.g., Claude Desktop):
{
"mcpServers": {
"neptime": {
"command": "npx",
"args": ["neptime-mcp-server"],
"env": {
"NEPTIME_API_KEY": "your-api-key-here"
}
}
}
}Or if installed globally:
{
"mcpServers": {
"neptime": {
"command": "neptime-mcp-server",
"env": {
"NEPTIME_API_KEY": "your-api-key-here"
}
}
}
}Tool | Description |
| List videos with pagination and sorting |
| Search for videos by keyword |
| Get trending videos |
| Get video details |
| Update a video you own |
| Delete a video you own |
| Like or dislike a video |
| Get channel information |
| Get videos from a channel |
| Subscribe to a channel |
| Unsubscribe from a channel |
| Get your subscriptions |
| Get your playlists |
| Get playlist details |
| Create a new playlist |
| Update a playlist |
| Delete a playlist |
| Add video to playlist |
| Remove video from playlist |
| Get comments on a video |
| Get comments on an article |
| Post a video comment |
| Post an article comment |
| Delete your comment |
| Like or dislike a comment |
| List articles |
| Get article details |
| Create an article |
| Update an article |
| Delete an article |
| Get watch history |
| Clear watch history |
| Get watch later list |
| Add to watch later |
| Remove from watch later |
| Get all categories |
| Get videos in a category |
| Report a video |
| Upload a video using a local path or base64 payload |
The Neptime API has the following rate limits:
Global: 1000 requests/hour, 60 requests/minute
Comments: 50/day, 10 seconds between posts
Subscriptions: 50/day
Reports: 10/hour, 50/day
Playlists: 100 max per user, 500 videos per playlist
# Clone the repository
git clone https://github.com/pasie15/neptime-mcp-server.git
cd neptime-mcp-server
# Install dependencies
npm install
# Build
npm run build
# Unit tests
npm test
# Run in development mode
npm run devMIT
Add a video to a playlist. Limit: 500 videos per playlist.
Args:
list_id: Playlist ID (required)
video_id: Video ID to add (required)
Returns: Confirmation with updated video count.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | Playlist ID | |
| video_id | Yes | Video ID to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds the limit of 500 videos, which is useful behavioral context beyond annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, but the 'Args:' section is somewhat redundant with the schema. Still, every sentence adds value and there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple add tool with 2 parameters and no output schema, the description is complete. It explains the action, limit, and return value ('Confirmation with updated video count'). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions in the schema. The description repeats the parameter names and types but adds minimal extra meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a video to a playlist' with a specific verb and resource. It includes a limit of 500 videos per playlist, and distinguishes from siblings like 'remove_video_from_playlist' and 'create_playlist'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (adding a video) but does not explicitly state when to use this tool vs alternatives like 'add_watch_later' or when not to use it. The limit provides some context but no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a video to your watch later list.
Args:
video_id: Video ID to add (required)
Returns: Confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds 'Returns: Confirmation' but fails to elaborate on the confirmation format or any potential side effects. The description does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, with a single sentence followed by an argument list. It is efficient but could be better structured for agent consumption (e.g., bullet points for return details).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with good schema coverage and annotations, the description is adequate but lacks details about the return value ('Confirmation' is vague) and does not mention any constraints or edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes 'video_id' with 100% coverage. The description repeats 'Video ID to add (required)' almost verbatim, adding no new semantic meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a video to your watch later list') with a specific verb and resource, distinguishing it from siblings like 'neptime_add_video_to_playlist' and 'neptime_remove_watch_later'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 (e.g., adding to a playlist) or when not to use it. No context about prerequisites or similar tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear all watch history. This action is IRREVERSIBLE.
Returns: Confirmation of history cleared.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and idempotentHint=true. The description adds the explicit warning 'IRREVERSIBLE' and states it returns confirmation, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and irreversibility. Every sentence adds essential information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless destructive action, the description covers the action, irreversibility, and return confirmation. Annotations fill in remaining details (idempotency, destructiveness).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, schema coverage is 100%. The description adds no parameter info, but none is needed. Baseline for no params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Clear all watch history', using a specific verb and resource. This distinguishes it from siblings like neptime_get_history (which reads history) and other delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description does not mention context, prerequisites, or when to avoid it, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new article/post.
Args:
title: Article title, 5-200 chars (required)
description: Short description, 15-500 chars (required)
text: Article body, min 50 chars (required)
tags: Comma-separated tags (optional)
category: Category ID (optional)
Returns: Created article object.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Article title | |
| description | Yes | Short description | |
| text | Yes | Article body text | |
| tags | No | Comma-separated tags | |
| category | No | Category ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description only notes that it returns the created object. It omits behavioral details such as whether duplicates are checked, whether title uniqueness is enforced, or what happens on validation failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a front-loaded purpose and a clear argument list. It avoids extraneous text, though using bullet points would improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and parameters adequately, but lacks error handling details, idempotency notes, and return type specifics beyond 'created article object'. Adequate for a create tool with full schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the description repeats schema info (min/max lengths, required fields) without adding new meaning. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new article/post,' specifying the action (create) and resource (article). Among sibling tools like update or delete, it uniquely identifies the creation operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 does not mention prerequisites, conditions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a comment on an article. Limit: 50 comments/day, 10s between posts.
Args:
article_id: Article ID (required)
text: Comment text, max 2000 chars (required)
Returns: Created comment object.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes | Article ID | |
| text | Yes | Comment text (max 2000 chars) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it is a write operation and mentions rate limits and max text length, but lacks details on authentication, failure modes, or side effects. Annotations are all false, so description carries the full burden and does an adequate job.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a bullet list, front-loaded with the primary action. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, inputs, output format, and constraints. Lacks details on error behavior or authentication, but for a simple create tool with no output schema, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, and the description merely repeats the same parameter information (article_id, text max 2000 chars). It adds no new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool posts a comment on an article, which is a specific verb and resource. It is distinct from sibling tools like 'neptime_create_video_comment' and 'neptime_delete_comment'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit rate limits (50/day, 10s between posts), providing important usage constraints. However, it does not specify when to avoid using the tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new playlist. Limit: 100 playlists max per user.
Args:
name: Playlist name, 2-100 chars (required)
description: Description, max 500 chars (optional)
privacy: public, private, or unlisted (default: private)
Returns: Created playlist object.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Playlist name | |
| description | No | Playlist description | |
| privacy | No | Privacy setting | private |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the creation behavior is clear. The description adds the limit and return object info, enhancing transparency without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a single sentence for purpose, followed by a bullet list for arguments. It is front-loaded and every sentence is useful, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately mentions the return of a playlist object. The limit and parameter details provide sufficient context for a create tool with three parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal value by restating parameters. It provides the default privacy value and character limits, but these are already in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a new playlist' with a specific verb and resource. It distinguishes itself from sibling tools like neptime_update_playlist and neptime_delete_playlist, and the limit information adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a usage limit (max 100 per user), guiding when the tool can be used. It does not explicitly mention alternatives for editing or other scenarios, but the limit provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a comment on a video. Limit: 50 comments/day, 10s between posts.
Args:
video_id: Video ID (required)
text: Comment text, max 2000 chars (required)
Returns: Created comment object.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID | |
| text | Yes | Comment text (max 2000 chars) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description adds value by stating the operation is a creation (mutation), includes rate limits, and mentions return type. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: one line for purpose, one line for rate limits, and bulleted args. No fluff, front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers purpose, constraints, and return type. It lacks error handling and prerequisites, but is fairly complete given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description repeats the parameter details from the schema without adding new meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool posts a comment on a video, with specific verb and resource. It distinguishes from siblings like 'create_article_comment' by explicitly mentioning videos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a rate limit (50/day, 10s between posts) which provides usage context, but does not explicitly compare with alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an article you own. This action is IRREVERSIBLE.
Args:
article_id: Article ID to delete (required)
Returns: Deletion confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes | Article ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true, but description adds 'IRREVERSIBLE' and 'you own', providing extra context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose, then numbered arguments and return. No wasted words, clearly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with no output schema, the description covers purpose, ownership, irreversibility, parameter, and return value. Complete and adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter description in schema matches the description. The description repeats the parameter info without adding new semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool deletes an article, specifies ownership ('you own'), and distinguishes from other delete tools like neptime_delete_comment or neptime_delete_video by emphasizing ownership.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies only delete your own articles but does not provide explicit guidance on when to use this tool versus alternatives like neptime_update_article or neptime_delete_comment, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a comment you own.
Args:
comment_id: Comment ID to delete (required)
Returns: Deletion confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| comment_id | Yes | Comment ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds ownership constraint and return value, complementing the destructiveHint annotation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus args section, no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All necessary context provided for the simple tool: action, ownership constraint, required parameter, and return type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single parameter with description. Description repeats 'Comment ID to delete' without adding new semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'delete' and the resource 'comment you own', distinguishing it from comment creation and retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies ownership constraint ('you own'), providing clear context for when to use. No mention of alternatives or when not to use, but adequate for a simple delete operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a playlist you own. This action is IRREVERSIBLE.
Args:
list_id: Playlist ID to delete (required)
Returns: Deletion confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | Playlist ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description highlights irreversibility and returns a confirmation, adding behavioral detail beyond annotations. It aligns with destructiveHint=true and provides useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with essential information front-loaded. Every sentence adds value, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and annotations present, the description is adequate. It explains purpose, parameter, and outcome. Minor gap: could mention success/error states beyond confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description of list_id. The description merely reiterates the schema, adding no new semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a playlist you own, specifying the verb and resource. It distinguishes from siblings like neptime_update_playlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage context by saying 'you own' but does not explicitly state when not to use or provide alternatives. The condition is helpful but lacks comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a video you own on Neptime.io. This action is IRREVERSIBLE.
Args:
video_id: Video ID to delete (required)
Returns: Confirmation of deletion.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds 'IRREVERSIBLE' and 'you own' context, emphasizing the permanence and ownership requirement, which enhances transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with one sentence and a brief args list. Every word serves a purpose, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter and no output schema, the description covers the necessary context: what it does, the required input, and that it returns a confirmation. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description merely restates the parameter's purpose from the schema ('Video ID to delete'). No additional semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and resource (video you own on Neptime.io). It distinguishes from sibling tools like neptime_delete_article by specifying 'video'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It indicates the tool is for deleting owned videos and warns that the action is irreversible. While it doesn't explicitly state when not to use it, the resource specificity makes it clear among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific article by ID.
Args:
article_id: Article ID (required)
Returns: Full article object with title, text, author, comments count.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes | Article ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, and idempotentHint. Description adds return info (title, text, author, comments count) but no additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is minimal and front-loaded: one line for purpose, then Args and Returns. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is complete. It specifies return fields, which compensates for lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description repeats the parameter name and requirement but adds no extra semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a specific article by ID' with a specific verb and resource. It distinguishes from siblings like 'neptime_list_articles' and 'neptime_get_article_comments'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or alternatives. The purpose is implied but lacks exclusions or context about when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comments on an article.
Args:
article_id: Article ID (required)
limit: Max results 1-100 (default: 20)
offset: Pagination offset (default: 0)
sort: Sort order - newest, oldest, top (default: newest)
Returns: Array of comments with user info, text, likes, replies.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes | Article ID | |
| limit | No | Max results | |
| offset | No | Pagination offset | |
| sort | No | Sort order | newest |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the return format ('Array of comments with user info, text, likes, replies'), which is not in the annotations. However, behavioral traits like auth needs or rate limits are absent, and the annotations already indicate safe read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. The Args list is somewhat redundant with the schema but not overly verbose. Each sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description provides return value structure, which is helpful. It covers all parameters and their constraints. However, it omits pagination behavior details and error handling, but is sufficient for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description merely restates parameter names and defaults. It adds no new semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get comments on an article' with a specific verb and resource. However, it does not explicitly distinguish from sibling tools like neptime_get_video_comments, relying on the tool name for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 (e.g., when to fetch video comments or other comment-related tools). The description lacks explicit context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all video categories.
Returns: Array of category objects with id, name, video count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=true, but the description adds the return format: 'Array of category objects with id, name, video count.' This provides specific behavioral detail beyond the general hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: one for purpose, one for return format. No unnecessary words. Information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and is straightforward, the description fully covers what the tool does and what it returns. An output schema is not present but the description compensates by naming the returned fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are present, so baseline score is 4. The description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Get all video categories', which is a specific verb+resource. The tool name 'neptime_get_categories' matches the action. There are no sibling tools for categories, so it is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives, but the lack of parameters and the simple retrieval nature makes it obvious. The description does not include exclusions, but the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get videos in a specific category.
Args:
category_id: Category ID (required)
limit: Max results 1-100 (default: 20)
offset: Pagination offset (default: 0)
Returns: Array of videos in the category.
| Name | Required | Description | Default |
|---|---|---|---|
| category_id | Yes | Category ID | |
| limit | No | Max results | |
| offset | No | Pagination offset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds minimal behavioral context beyond annotations (e.g., returns array of videos). Annotations already indicate read-only, non-destructive, idempotent behavior. No additional traits disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one-line purpose and structured parameter list. Every sentence is essential, with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with 3 params and no output schema, the description fully covers purpose, parameters, and return type. Pagination is implied by limit/offset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; descriptions in schema already explain each parameter. The description repeats this info without adding new meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get videos') and the resource ('in a specific category'), distinguishing it from siblings like neptime_get_channel_videos and neptime_list_videos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide when-to-use or alternative tools. Usage is implied by the tool name and context, but no guidance on when to prefer this over similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get channel information by ID.
Args:
channel_id: Channel ID (required)
Returns: Channel object with name, avatar, subscriber count, video count, description.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, and the description aligns with these. It adds value by describing the return object (Channel with name, avatar, etc.), which is beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two short paragraphs. Every sentence is necessary and front-loaded with the core purpose. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one required parameter, no output schema), the description adequately covers purpose, parameter, and return structure. Annotations provide behavioral guarantees, making the description complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the only parameter. The description repeats the parameter name and requirement, but adds no additional meaning beyond what the schema already provides. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get channel information by ID,' specifying the action and resource. It distinguishes itself from sibling tools like neptime_get_channel_videos and neptime_get_playlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only explains what the tool does, with no explicit guidance on when to use it versus alternatives or when not to use it. Usage is implied by the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get videos from a specific channel.
Args:
channel_id: Channel ID (required)
limit: Max results 1-100 (default: 20)
offset: Pagination offset (default: 0)
Returns: Array of videos from the channel.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel ID | |
| limit | No | Max results | |
| offset | No | Pagination offset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent hints. The description adds that it returns an array of videos but doesn't disclose other behaviors (e.g., rate limiting, auth requirements). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured, but it largely duplicates schema information. Still, no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description minimally explains return type. Annotations cover safety. Could add more about return structure but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers all parameters with descriptions. The description repeats this information without adding new insight, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets videos from a specific channel. However, it does not differentiate from sibling tools like 'neptime_get_category_videos' or 'neptime_get_playlist_videos' (if existed), but it is still clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it doesn't mention when to use 'neptime_search_videos' or 'neptime_list_videos' instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get your video watch history.
Args:
limit: Max results 1-100 (default: 20)
offset: Pagination offset (default: 0)
Returns: Array of watched videos with timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| offset | No | Pagination offset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool is safe and read-only. The description adds that it returns an array with timestamps and mentions pagination (limit, offset), providing behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences plus bullet-pointed arguments. Every part is necessary, and it is front-loaded with the core purpose. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description mentions the return type (array with timestamps) and explains pagination parameters. It covers the essential information for a simple read operation, though it could detail ordering or optional filters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds default values (20, 0) and a range for limit (1-100), but these are already in the schema. No additional semantic meaning is provided beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get your video watch history,' clearly identifying the verb (Get) and resource. The title 'Get Watch History' reinforces this. It distinguishes from siblings like neptime_clear_history (destructive) and neptime_get_watch_later (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like neptime_search_videos or neptime_get_watch_later. Usage is implied by name and title, but no when-to-use or when-not-to-use information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific playlist including videos.
Args:
list_id: Playlist ID (required)
Returns: Playlist object with videos array.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | Playlist ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, covering safety. Description adds return type but no further behavioral context (e.g., error responses or idempotency implications).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is short and front-loaded with purpose. The args list is clear but could be more formal. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description covers input and output shape. Lacks error behavior but acceptable given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, baseline is 3. Description repeats 'Playlist ID (required)' but adds no syntax, format, or constraints beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get details of a specific playlist including videos,' specifying the exact resource and action. It naturally distinguishes from sibling tool neptime_get_playlists (plural) which returns a list of playlists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use when you need details of a single playlist by ID. No explicit guidance on when not to use (e.g., for listing playlists, use neptime_get_playlists) or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all playlists owned by the authenticated user. Limit: 100 playlists max.
Returns: Array of playlist objects with id, name, video count, privacy.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, etc. Description adds the 100-playlist limit and return structure, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, then limit, then return format. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a parameterless list tool: mentions limit and return fields. Could clarify ordering or pagination, but not essential given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so schema coverage is 100% trivially. Baseline 4 applies; description doesn't need to add param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets all playlists owned by the authenticated user, specifies a 100-playlist limit, and describes return fields. Distinguishes from sibling neptime_get_playlist (singular) by indicating it returns all playlists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when a list of owned playlists is needed. Lacks explicit when-not-to-use or alternatives, but the purpose is straightforward with no parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get list of channels you are subscribed to.
Args:
limit: Max results 1-100 (default: 20)
offset: Pagination offset (default: 0)
Returns: Array of subscribed channels.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| offset | No | Pagination offset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds pagination details (limit, offset) and return type, which is useful but does not disclose beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear two-sentence purpose, a bulleted list of args, and a return statement. Every sentence is necessary and no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with no output schema, the description adequately explains the resource and pagination. It could mention default pagination behavior but is generally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description only restates the defaults and ranges from the schema. It adds no new meaning beyond what is already in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get list of channels you are subscribed to.' It uses a specific verb ('Get') and specifies the resource (subscriptions), distinguishing it from sibling tools like neptime_get_playlists or neptime_subscribe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for viewing subscribed channels, which is distinct from subscribing/unsubscribing. It does not explicitly state when not to use it, but the purpose is straightforward and contextually clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific video.
Args:
video_id: Video ID (required)
Returns: Full video object with title, description, views, likes, comments count, channel, upload date, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show read-only and idempotent; description adds return fields (views, likes, etc.) beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose, args, and returns; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple get tool; could mention error handling or output format details, but return fields are listed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single parameter fully; description adds no extra semantic meaning beyond required flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets detailed information about a specific video, distinguishing it from list or search siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives; usage is implied as a standard get-by-ID tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comments on a video.
Args:
video_id: Video ID (required)
limit: Max results 1-100 (default: 20)
offset: Pagination offset (default: 0)
sort: Sort order - newest, oldest, top (default: newest)
Returns: Array of comments with user info, text, likes, replies.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID | |
| limit | No | Max results | |
| offset | No | Pagination offset | |
| sort | No | Sort order | newest |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's safety alignment is covered. It adds value by specifying the return structure (array with user info, text, likes, replies) and pagination behavior via limit/offset, which enhances transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely concise: one line for purpose, then a bulleted list of parameters, and one line for returns. Every sentence adds value, no fluff, and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list endpoint with 4 parameters and no output schema, the description adequately covers purpose, parameters, pagination, sort options, and return structure. It is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters with descriptions, defaults, and constraints. The description redundantly lists them but adds no new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Get comments on a video,' a clear verb+resource statement. It unambiguously identifies the operation and resource, and among siblings like neptime_create_video_comment or neptime_get_article_comments, it's distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it's for reading comments, but lacks when-not-to-use or explicit comparisons to sibling tools like neptime_get_article_comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get your watch later list.
Returns: Array of videos saved for later.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description only adds 'Returns: Array of videos saved for later.' This provides minimal extra behavioral context beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, extremely concise, with purpose front-loaded. Every word serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and annotations covering behavioral traits, the description is fairly complete. It could specify the returned video object structure, but for a simple list retrieval, it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema description coverage is 100% (trivially). The description need not add parameter details; baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get your watch later list', specifying the verb and resource. It distinguishes from siblings like neptime_add_watch_later and neptime_get_history by focusing on retrieving the watch later list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it doesn't clarify when to use get_watch_later over get_history or list_videos, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List articles/posts from Neptime.io.
Args:
limit: Max results 1-100 (default: 20)
offset: Pagination offset (default: 0)
Returns: Array of article objects with id, title, description, author, date.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| offset | No | Pagination offset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds return format details (array of article objects with fields), which enhances transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (three lines for arguments, one for returns), structured clearly, and each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes pagination and return fields. No output schema exists, but the description compensates. Could mention sorting or ordering, but not essential for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with full parameter details. The description restates schema info (range, default) but does not add new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists articles/posts from Neptime.io, using a specific verb and resource. It differentiates from siblings like neptime_get_article (singular) and neptime_list_videos (videos).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides pagination parameters but lacks explicit when-to-use guidance. However, the context signal of sibling tools shows no alternative for listing articles, so usage is implicitly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List videos from Neptime.io with pagination and sorting.
Args:
limit: Max results 1-100 (default: 20)
offset: Pagination offset (default: 0)
sort: Sort order - newest, oldest, views, likes (default: newest)
category: Filter by category ID (optional)
Returns: Array of video objects with id, title, views, likes, duration, thumbnail, channel info.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (1-100) | |
| offset | No | Pagination offset | |
| sort | No | Sort order | newest |
| category | No | Filter by category ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds output structure (array of video objects) which is behavioral, but doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one-sentence overview, bulleted args, and return description. Front-loaded and no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, and output format. With no output schema, the return description is helpful. Could mention the tool's scope (all videos) but annotations cover read-only nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description's parameter list essentially repeats the schema's descriptions (e.g., limit: 'Max results 1-100 (default: 20)'). No new semantic value added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'videos' from Neptime.io, distinguishing it from tools like neptime_search_videos by emphasizing pagination and sorting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs. alternatives like neptime_search_videos or neptime_get_channel_videos. The description lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Like or dislike a comment.
Args:
comment_id: Comment ID (required)
rating: "like", "dislike", or "none" to remove rating (required)
Returns: Updated like/dislike counts.
| Name | Required | Description | Default |
|---|---|---|---|
| comment_id | Yes | Comment ID | |
| rating | Yes | Rating action |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds that 'none' removes the rating and that the tool returns updated counts, providing behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using two sentences and a bullet list for args. Every part is necessary and no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description mentions return values (updated counts). For a simple rate action with well-defined parameters, this is sufficient and complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description clarifies the meaning of 'none' (removes rating) but adds little beyond the enum values already defined in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Like or dislike a comment,' specifying the verb and resource. The sibling tool 'neptime_rate_video' rates videos, so there is clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (rate comments) but does not explicitly state when to use or not use this tool versus alternatives like 'neptime_rate_video' or 'neptime_delete_comment.' No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Like or dislike a video.
Args:
video_id: Video ID (required)
rating: "like", "dislike", or "none" to remove rating (required)
Returns: Updated like/dislike counts.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID | |
| rating | Yes | Rating action |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint and readOnlyHint, and the description adds that the tool returns updated like/dislike counts and explains the 'none' rating to remove. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one-line purpose, bulleted args, and return statement. Every word serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with no output schema, the description covers all necessary aspects: what it does, parameters, and return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context for rating values, e.g., 'none' to remove rating, which goes beyond the schema's 'Rating action' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Like or dislike a video' with specific verb and resource. It distinguishes from sibling tools like neptime_rate_comment by specifying video ratings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for rating videos without explicit when-to-use or alternatives. It is clear enough from context, but lacks explicit guidance on when not to use or comparative alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a video from a playlist.
Args:
list_id: Playlist ID (required)
video_id: Video ID to remove (required)
Returns: Confirmation with updated video count.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | Playlist ID | |
| video_id | Yes | Video ID to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds that it returns confirmation with updated video count, which is useful. No contradictions. Could mention if removal affects other users or if it's reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences and an args list. It is front-loaded with the action and efficiently communicates the core information with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation with two required string params and no output schema, the description covers the purpose, parameters, and return value. It is complete enough for an agent to use correctly, though it could mention potential errors or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents both parameters. The description repeats them without adding extra meaning beyond what the schema provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove a video from a playlist,' which is a specific verb and resource. It distinguishes from siblings like 'neptime_add_video_to_playlist' and 'neptime_remove_watch_later' by focusing on playlist removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit when-to-use or alternatives. For a simple removal, it's implied, but no guidance on prerequisites (e.g., ownership) or when not to use (e.g., if playlist is invalid).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a video from your watch later list.
Args:
video_id: Video ID to remove (required)
Returns: Confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotency (idempotentHint=true) and non-destructiveness (destructiveHint=false). The description adds that it returns a confirmation, which is useful but not critical. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, with two sentences and one argument listing. It is front-loaded and efficient, though slightly informal in structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one parameter and no output schema, the description fully covers what the tool does, what it expects, and what it returns. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'video_id' with description 'Video ID'. The description merely repeats this info, adding no additional semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes a video from the watch later list. It uses a specific verb and resource, distinguishing it from sibling tools like neptime_add_watch_later and neptime_remove_video_from_playlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for removing videos from watch later but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though sibling tools exist for similar actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a video for violating community guidelines. Limit: 10 reports/hour, 50/day.
Args:
video_id: Video ID to report (required)
reason: spam, harassment, hate_speech, violence, nudity, copyright, misinformation, or other (required)
description: Additional details, max 500 chars (optional)
Returns: Report confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID to report | |
| reason | Yes | Report reason | |
| description | No | Additional details (max 500 chars) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the tool is not read-only but not destructive. The description adds rate limits and return value ('Report confirmation'), but does not disclose whether reports are anonymous or if multiple reports for the same video are allowed. With annotations present, the bar is lower, and the description provides some additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a bullet list of args and return. It is highly concise with no wasted words. The structure is clear: purpose, rate limit, parameter list, return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple reporting tool, the description covers purpose, rate limits, required and optional parameters, and return value. No output schema exists, but the return value is stated. Some minor details (e.g., anonymity, duplicate report handling) are missing, but overall it is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description repeats parameter names and constraints (e.g., max 500 chars for description) already present in the schema. It does not add new semantic meaning beyond listing the allowed reasons in the description text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Report a video for violating community guidelines.' This is a specific verb+resource combination, and it effectively distinguishes from sibling tools like 'neptime_rate_video' or 'neptime_delete_video.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions rate limits (10 reports/hour, 50/day), providing clear context for usage. It does not specify when not to use or alternatives, but no sibling tool serves the same function, so the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for videos on Neptime.io by keyword.
Args:
q: Search query (required, 1-200 chars)
limit: Max results 1-100 (default: 20)
offset: Pagination offset (default: 0)
Returns: Array of matching videos with relevance scoring.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query | |
| limit | No | Max results | |
| offset | No | Pagination offset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns an 'Array of matching videos with relevance scoring,' which provides extra behavioral context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences up front explaining the purpose, followed by a compact parameter list. No wasted words, and the key action is stated first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but the description mentions the return type and relevance scoring, which is sufficient for understanding what to expect. It covers the essential aspects for a simple search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters. The description restates constraints (e.g., query length, limit range) and defaults, providing a quick reference but adding minimal new information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Search for videos on Neptime.io by keyword.' It distinguishes from siblings like neptime_list_videos (lists all videos) and neptime_trending_videos (lists trending), as it's specifically for keyword-based search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use this tool (search by keyword) but doesn't explicitly exclude alternatives like list_videos or trending_videos. However, given the naming and context, it's clear that this is the dedicated search tool, so usage is well-understood.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subscribe to a channel. Limit: 50 subscriptions per day.
Args:
channel_id: Channel ID to subscribe to (required)
Returns: Subscription confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel ID to subscribe to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true (idempotent), destructiveHint=false (non-destructive), and readOnlyHint=false (write operation). Description adds the daily limit and confirmation return, but does not elaborate on side effects or authorization needs. Adequate but not extensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with two brief paragraphs. Could be slightly more streamlined by removing the Args/Returns section, but overall efficient. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple tool with one required parameter, no output schema, and existing annotations, the description covers the essential: purpose, limit, and return. Lacks context about prerequisites or error cases, but sufficient for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (channel_id) with 100% schema coverage. The description re-iterates it is required but adds no new semantic meaning beyond the schema's description. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Subscribe to a channel' with a verb and resource. It distinguishes from sibling tools like neptime_unsubscribe and neptime_get_subscriptions. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a daily limit (50 subscriptions per day), offering practical guidance. Does not explicitly state when to use vs alternatives, but the sibling context implies it is for subscribing as opposed to unsubscribing or listing subscriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get trending videos on Neptime.io.
Args:
limit: Max results 1-100 (default: 20)
period: Trending period - day, week, month (default: week)
Returns: Array of trending videos sorted by popularity.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| period | No | Trending period | week |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that it returns an array sorted by popularity, but does not disclose additional behavioral traits like pagination or rate limits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences for purpose and a bullet-style args list. Every sentence adds value, no filler. Front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two parameters and robust annotations, the description adequately covers purpose, parameters, and return type. It could mention pagination or note the read-only nature, but annotations already cover safety. Returns 'array of trending videos sorted by popularity' is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter schema coverage is 100%, so the description adds marginal value by restating limit range and period enum with defaults, which are already in the schema. No new semantic meaning beyond schema is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets trending videos on Neptime.io, sorted by popularity. This distinguishes it from list_videos (all videos) and search_videos (search), but it does not explicitly differentiate from get_category_videos or get_channel_videos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like neptime_list_videos or neptime_search_videos. It implies usage for trending content but lacks when-not-to-use or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unsubscribe from a channel.
Args:
channel_id: Channel ID to unsubscribe from (required)
Returns: Unsubscription confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| channel_id | Yes | Channel ID to subscribe to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true; description adds nothing beyond basic return information. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with no fluff; key information (purpose, parameter, return) is front-loaded in two sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameter with annotations covering idempotency, the description is largely sufficient, though it lacks error or prerequisite info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the schema description incorrectly says 'subscribe to' while the tool description correctly says 'unsubscribe from'. Description adds minimal extra meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Unsubscribe from a channel' with a specific verb and resource, distinguishing it from sibling tools like neptime_subscribe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., neptime_subscribe) or prerequisites like being currently subscribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an article you own.
Args:
article_id: Article ID (required)
title: New title (optional)
description: New description (optional)
text: New body text (optional)
tags: New tags (optional)
category: New category ID (optional)
Returns: Updated article object.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes | Article ID | |
| title | No | New title | |
| description | No | New description | |
| text | No | New body text | |
| tags | No | New tags | |
| category | No | New category ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare idempotentHint=true and destructiveHint=false. The description adds that it returns the updated article object but does not discuss side effects, error conditions, or ownership validation beyond the basic statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, uses a list format, and includes a return statement. It is front-loaded with the core action. However, it is somewhat redundant with the schema, repeating parameter details that could be omitted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema, the description lacks context on error behavior (e.g., missing article, permission issues) and does not clarify whether updating with empty values clears fields. It covers the basics but is incomplete for a safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter already having a description. The description merely restates the schema's parameter list and indicates optionality, adding no new semantic information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an article that the user owns, with a specific verb and resource. It distinguishes from sibling tools like create_article and delete_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the article must be owned by the user but does not provide explicit guidance on when to use this tool versus alternatives like create_article or update_video. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a playlist you own.
Args:
list_id: Playlist ID (required)
name: New name, 2-100 chars (optional)
description: New description (optional)
privacy: public, private, or unlisted (optional)
Returns: Updated playlist object.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | Playlist ID | |
| name | No | New name | |
| description | No | New description | |
| privacy | No | Privacy setting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds ownership requirements beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). It also specifies the return value ('Updated playlist object'), which is not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a clear front-loaded purpose, followed by a bullet-style parameter list and return statement. Every sentence is necessary and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with no output schema, the description covers all parameters, ownership, and return value. It leaves no critical gaps, making it fully informative for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description rephrases constraints (e.g., '2-100 chars' for name) and lists enum values for privacy, adding clarity. It does not fully explain the list_id ownership context beyond the tool-level ownership statement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a playlist you own,' specifying the verb 'update' and resource 'playlist,' and includes an ownership qualifier that distinguishes it from sibling tools like create, delete, or get playlists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you own a playlist and want to modify it, but lacks explicit guidance on when not to use it or alternatives (e.g., creating a new playlist instead). No sibling tool is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a video you own on Neptime.io.
Args:
video_id: Video ID to update (required)
title: New title (5-100 chars, optional)
description: New description (max 5000 chars, optional)
tags: Comma-separated tags (optional)
privacy: public, private, or unlisted (optional)
Returns: Updated video object.
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID to update | |
| title | No | New title | |
| description | No | New description | |
| tags | No | Comma-separated tags | |
| privacy | No | Privacy setting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds return type but not additional behavioral context like error handling or permission details. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs: first line states purpose, second lists parameters with constraints. No redundancy, well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameters and return type, but lacks details on error conditions, ownership verification, or effects when video_id is invalid. Adequate for a straightforward update tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds minimal value by restating constraints already in schema (e.g., 5-100 chars). No new semantic information beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update a video you own on Neptime.io', specifying the action, resource, and ownership condition. It distinguishes itself from sibling update tools like neptime_update_article and neptime_update_playlist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when updating a video you own, but lacks explicit guidance on when to use versus alternatives or when not to use. No mention of fallback or exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a video to Neptime.io through the live /videos/upload endpoint.
Provide either video_path for a local file available to the MCP server, or video_base64 plus video_filename. Videos can be mp4, mov, webm, mpeg, avi, or mkv. The default privacy is private (1) for safety.
Args:
title: Video title (required)
description: Video description (required)
tags: Comma-separated tags (required)
video_path OR video_base64: Video file source (required)
video_filename: Filename when using video_base64
thumbnail_path OR thumbnail_base64: Optional thumbnail
category_id: Optional category ID
privacy: 0=public, 1=private, 2=unlisted (default: 1)
age_restriction: 1=all ages, 2=18+ (default: 1)
is_short: true for short-form video (default: false)
Returns: Uploaded video object with video_id, URL, stream URL, thumbnail, approval status, and privacy.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (all false) are consistent with a write operation. Description adds return object details and safety default. Could mention async processing or file size limits but overall good transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear header and bullet-pointed args. The Args list is thorough but not overly verbose. Could trim redundant phrasing but still concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers upload process, parameter combinations, and return values. Lacks file size limits or authentication prerequisites. Given the complexity and many siblings, it sufficiently distinguishes from other tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite empty input schema, description compensates fully with a detailed Args list covering data types, defaults, required/optional, and enum mappings (privacy, age_restriction). Schema coverage is effectively 100% due to documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Upload a video to Neptime.io' with a specific endpoint, distinct from sibling tools like update_video or delete_video. It specifies the resource and action unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on choosing between video_path and video_base64, listing required args and defaults. Lacks explicit 'when not to use' but given it's the only upload tool, the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.0neptime_add_video_to_playlistneptime_add_watch_laterneptime_clear_historyneptime_create_articleneptime_create_article_commentneptime_create_playlistneptime_create_video_commentneptime_delete_articleneptime_delete_commentneptime_delete_playlistneptime_delete_videoneptime_get_articleneptime_get_article_commentsneptime_get_categoriesneptime_get_category_videosneptime_get_channelneptime_get_channel_videosneptime_get_historyneptime_get_playlistneptime_get_playlistsneptime_get_subscriptionsneptime_get_videoneptime_get_video_commentsneptime_get_watch_laterneptime_list_articlesneptime_list_videosneptime_rate_commentneptime_rate_videoneptime_remove_video_from_playlistneptime_remove_watch_laterneptime_report_videoneptime_search_videosneptime_subscribeneptime_trending_videosneptime_unsubscribeneptime_update_articleneptime_update_playlistneptime_update_videoneptime_upload_videoScored across 39 tools
Each tool targets a distinct resource and action, clearly differentiated by the resource name (video, article, playlist, channel, comment, etc.). Even similar actions like 'get_article_comments' vs 'get_video_comments' are unambiguous due to the different resource nouns.
All tools follow a consistent 'neptime_verb_noun' pattern. Verbs are appropriate (get, list, create, update, delete, add, remove, etc.) and nouns clearly indicate the resource. There is no mixing of conventions.
With 39 tools, the server covers a wide range of operations for a video platform including articles, playlists, channels, and subscriptions. While on the higher end, each tool serves a distinct purpose and is justified by the scope of the platform.
The tool surface provides comprehensive CRUD and lifecycle operations for videos, articles, playlists, and comments, plus search, trending, ratings, and subscriptions. Minor gaps exist, such as user profile management and channel creation, but the core workflows are well-covered.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
Build, run, schedule, and publish AI video pipelines to YouTube and TikTok from any MCP client.
YouTube transcripts, search, channel browsing, and playlists for AI agents via MCP.
Turn long videos into short, captioned viral clips from your AI assistant. 28 tools, OAuth.
