tokportal-mcp

Official

by tokportal

Overview Schema Related Servers Score Discussions

Python

Remote

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation2/5
Many tools have overlapping purposes, especially around bundle and account management. For example, there are multiple 'finalize', 'publish', 'configure', and 'request corrections' tools for both accounts and videos, and the boundary between bundle-level and individual-video operations is unclear.
Naming Consistency4/5
Tool names consistently follow a verb_noun pattern (e.g., tokportal_list_bundles, tokportal_get_account), and naming is mostly predictable. Minor inconsistency exists with 'finalize_bundle_account' vs 'finalize_bundle' and some tools like 'rewarm_account' which use different terminology.
Tool Count2/5
With 91 tools, this server has far too many for typical agent comprehension and navigation. While the domain is complex (bundle lifecycle, webhooks, analytics, etc.), the count is overwhelming and suggests the API surface has been exposed at too granular a level.
Completeness4/5
The tool surface covers the full bundle lifecycle (create, configure, publish, manage videos), account management, analytics, webhooks, and credits. There are no obvious dead ends; the completeness appears strong. Minor gaps exist (e.g., no tool to delete a bundle, and some bulk operations are missing), but overall it's well-covered.
Average 3.6/5 across 91 of 91 tools scored. Lowest: 1.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds no behavioral context beyond that, such as what 'pulse' means in terms of data aggregation, time windows, or rate limits. It does not contradict annotations but fails to improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (4 words) but lacks structure and substance. While brevity is valued, here it sacrifices all meaningful information, making it more of a title than a useful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters, no output schema, and numerous sibling tools. The description provides no context about return values, parameter usage, or how this analytics tool differs from others. It is severely incomplete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 8 parameters with descriptions that are trivial ('query parameter <name>'). The tool description does not explain any parameter semantics, such as the meaning of 'post', 'account', or the date range defined by 'to' and 'from'. It adds no value beyond the weak schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get comment pulse analytics' is a minimal verb+noun phrase but does not define what 'comment pulse' is or how it differs from sibling analytics tools like tokportal_get_analytics_series. It lacks specificity and fails to distinguish the tool's unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context that would help an agent decide between this and other analytics or comment-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description carries a lower burden. However, it adds no behavioral context whatsoever—no details on what unpublishing entails, whether it can be reversed, or if it has side effects on related resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that merely repeats the name. It is under-specified rather than concise, offering no useful information for a tool with two parameters and destructive behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only two parameters and no output schema, the description is completely inadequate. It fails to explain return values, error conditions, or the effect of the operation, leaving the agent with insufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (id, idempotency_key) are documented in the input schema. The description adds no additional meaning beyond the schema, achieving the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Unpublish a bundle.' is a tautology of the tool name and title. It restates the verb+resource without adding any new information or distinguishing from sibling tools like publish_bundle or update_bundle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., updating a bundle, creating a new one). There is no mention of prerequisites, sequencing, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering basic safety. The description adds no behavioral context beyond that—no mention of scoping, pagination, or response characteristics. Since annotations already carry the safety profile, the description's lack of additional transparency is a missed opportunity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one phrase) but under-specified. It does not front-load key information or structure content effectively. Every sentence should earn its place, but this single sentence conveys minimal useful information, making it insufficient rather than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no required ones, no output schema, and a complex context (many analytics siblings), the description is severely incomplete. It does not explain what the time series contains (e.g., metrics, accounts, date ranges), how defaults interact, or what the return format looks like. The agent cannot infer adequate usage or interpret results from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 100%, the parameter descriptions are minimal (e.g., 'query parameter to') and add no meaning beyond the parameter name and type. The tool description itself does not explain parameter semantics. For example, the difference between 'cumulative', 'gained', and 'snapshot' mode is not clarified. With only tautological schema descriptions, the tool description fails to add value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get analytics time series' identifies a specific resource (time series) and a verb (get), which is clear at a high level. However, it does not differentiate from many analytics siblings like tokportal_get_analytics_dashboard, tokportal_get_account_analytics, or tokportal_get_video_analytics. The purpose is moderately clear but lacks specificity about what aspect of analytics is captured.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the many analytics siblings (e.g., when to use this instead of tokportal_get_analytics_dashboard or tokportal_get_account_analytics). There is no mention of context, prerequisites, or exclusions. This leaves the agent without decision-making information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context (e.g., whether data is real-time, if it requires specific permissions, or if it triggers any side effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks structure and important details. It is under-specified rather than efficiently informative, providing no front-loaded key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter, no output schema, and annotations that cover safety, the description is still incomplete. It fails to explain what a 'compatibility view' is, when to use it, or what distinguishes it from other analytics tools, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the 'id' parameter has a description 'Saved account ID.'). The description does not add any further meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'get' and the resource 'account analytics compatibility view', which identifies a specific resource. However, the term 'compatibility view' is ambiguous and does not clearly explain what the tool returns or how it differs from sibling tools like tokportal_get_analytics_account or tokportal_refresh_account_analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or cases where another tool would be preferred, leaving the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, clearly framing this as a safe read operation. The description adds no behavioral detail beyond the title, but does not contradict annotations, so a baseline score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words), which could be seen as concise, but it under-specifies the tool's purpose. It sacrifices necessary detail for brevity, failing to earn its place by providing minimal value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 7 optional parameters and no output schema, the description should explain the tool's scope (e.g., does it list all bundles for the current user? across all platforms?). The current description leaves significant gaps in understanding what is listed and how filtering works.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with seven parameters fully documented in the schema. The description provides no additional context about parameter meanings, acceptable formats, or how they interact (e.g., does platform filter the bundles listed?). Baseline 3 is correct as schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List bundles' clearly identifies the verb (list) and resource (bundles), but lacks differentiation from sibling tools like tokportal_list_account_bundles or tokportal_list_bundle_videos. Without context about what 'bundles' are, the agent cannot distinguish this tool from others that also list bundles in different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as tokportal_list_account_bundles or tokportal_get_bundle. There is no mention of prerequisites, context, or exclusions, leaving the agent without decision-making information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no behavioral details beyond what annotations provide, such as what pricing data is returned (base costs, tiers?) or if external API calls are made. This is adequate but not additive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at 3 words. While it's slightly under-informative for a tool in a large API surface, it does not waste words. A front-loaded one-liner is acceptable for a simple zero-param query.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the sibling set (many credit/billing related tools), a 'Get credit pricing' description is too sparse. There is no output schema to explain return values, and no clarification on what pricing scope or structure is returned. For a simple zero-param tool, this is minimally complete but lacks helpful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters and 100% schema description coverage, there is nothing missing from the schema. The description does not need to add parameter meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get credit pricing' is largely a tautology of the tool name and title. It states what the tool does (retrieve pricing) but gives no detail about what kind of credit pricing (e.g., per-segment, per-platform, bulk discounts?), which is needed given the large set of sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like tokportal_get_credit_balance or tokportal_list_credit_transactions. The context of pricing discovery is implied, but there is no mention of prerequisites or scenarios where other credit-related tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only, non-destructive, non-idempotent, but the description adds only 'creates a standalone downloadable HTML'. It does not disclose side effects (e.g., whether the report is stored, costs, or generation time), nor does it expand on the behavioral implications of parameters like filtering by date or platform.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short sentences, front-loading the action. However, it could be slightly more structured (e.g., separated details) or include a brief bullet, but overall it is efficient and avoids verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 nested parameters, no output schema, no annotations), the description is too brief. It does not explain the report's content, output details (e.g., download link vs. inline HTML), or any constraints (e.g., date range limits). An agent would likely need additional information to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for top-level parameters, but the description adds no semantic meaning to either 'body' (with 11 nested fields lacking descriptions) or 'idempotency_key'. The description could have explained key parameters like 'from', 'to', 'template', but it does not, leaving the agent to infer meaning solely from type/format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Export' and the resource 'analytics report HTML', specifying the output format. It distinguishes from siblings like 'tokportal_export_analytics_videos' by focusing on an HTML report, though it doesn't elaborate on what the report contains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'tokportal_get_analytics_dashboard' or 'tokportal_create_analytics_report'. There is no mention of prerequisites, preconditions, or limitations, leaving the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint: true, idempotentHint: true, destructiveHint: false) already declare the tool as a safe, idempotent read operation. The description adds no further behavioral context—no mention of caching, response format, permissions, or side effects. Since annotations carry the behavioral burden here, a 3 is appropriate as the description neither adds nor contradicts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short at three words ('Get a bundle'). While this is concise, it borders on under-specification. However, for a simple lookup tool with full annotation coverage and a single parameter, there is no fluff or wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 required param, no enums, no output schema), the description is minimally adequate. The agent can infer that providing a bundle ID returns bundle data, but complete absence of info about the return value shape or what constitutes a 'bundle' (vs bundle account, bundle video, etc.) leaves moderate ambiguity among the 80+ sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—the schema already documents the single 'id' parameter with type, format (uuid), and description 'Bundle ID.' The description adds no additional meaning beyond what the schema provides, so baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a bundle' uses a generic verb and resource, but among 80+ sibling tools there are many that operate on bundles (create, update, publish, unpublish, reset, finalize, get_bundle_account, get_bundle_publish_readiness, etc.). The description does not distinguish 'get a bundle' from these other bundle-related tools, providing no specificity about what makes this tool unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like get_bundle_account, get_bundle_publish_readiness, or list_bundles. The name suggests retrieving a single bundle by ID, but there is no explicit when-to-use or when-not-to-use context, leaving the agent to infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no extra behavioral context beyond what annotations provide (e.g., no mention of rate limits, response format, or data freshness). Since annotations carry the burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single four-word sentence, which is very concise and front-loaded. However, it sacrifices informativeness for brevity—it does not explain what 'analytics' includes or how it differs from similar tools. Adequate conciseness but not optimal structure for an agent to act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 65+ sibling tools (including many analytics variants), the description is too brief to provide complete context. It does not describe the return value structure, which parameters affect results, or how this tool fits into the analytics workflow. Adequate for a simple fetch, but insufficient given the ecosystem.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the single 'id' parameter having a description 'Video ID.' The tool description 'Get single video analytics.' adds no additional meaning or constraints for the parameter beyond what the schema already conveys. Baseline 3 for full schema coverage with no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get single video analytics.' clarifies the tool retrieves analytics for a single video, which is slightly more specific than the name. However, it does not differentiate from sibling analytics tools like 'tokportal_get_account_analytics' (account-level) or 'tokportal_list_account_video_analytics' (list vs single). It lacks a clear verb-resource distinction with context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus alternatives (e.g., tokportal_list_account_video_analytics for listing, or tokportal_get_analytics_dashboard for aggregated views). There is no mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is not read-only, idempotent, or destructive, but give no further hints. The description does not disclose behavioral traits such as whether adding slots can fail, what state changes occur, or if it requires certain permissions. It adds minimal value beyond the annotations, which already show it's a mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the core action without fluff. It efficiently communicates the tool's purpose, though it could benefit from a bit more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain what the tool returns or what success looks like. It does not. Additionally, the tool has nested objects and three parameters, but the description doesn't help the agent understand the action's scope or behavior, leaving significant gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional meaning to parameters like 'id', 'quantity', or 'idempotency_key' beyond their names and types. For example, it doesn't explain what 'edit slots' are or the effect of the quantity on the bundle.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add edit slots to a bundle' clarifies the verb and resource, distinguishing it from siblings like tokportal_add_video_slots. However, it lacks specificity about what 'edit slots' are or how they relate to bundles, making the purpose somewhat vague for an agent unfamiliar with the domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like tokportal_add_video_slots or tokportal_create_bundle. The agent is left to infer usage from the name and description, with no mention of prerequisites, constraints, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. However, the description adds no additional behavioral context (e.g., rate limits, required scopes, or output format traits). It 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (4 words) and front-loaded, but it is under-specified for a tool with 7 parameters. It is not a tautology, but it lacks sufficient substance to be considered well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and the complexity of analytics exports, the description is incomplete. It does not explain what the CSV contains, any limitations, or how the output relates to video analytics. The agent cannot fully gauge the tool's applicability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 7 parameters have descriptions. The tool description adds no extra meaning beyond what's in the schema, achieving the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action (export) and resource (analytics videos) and format (CSV). It is clear but does not distinguish this tool from siblings like tokportal_export_analytics_report_html or tokportal_get_analytics_series, which also deal with analytics exports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not contrast with other analytics tools or explain use cases like exporting raw video data vs. getting a dashboard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations clearly indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds minimal behavioral context beyond 'delivered' status, which is not explained. With strong annotations, this scores a 3 as the description adds little extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no filler. It is front-loaded with the key action and resource. However, the word 'delivered' could be expanded in one additional sentence to clarify the account state without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a tool that returns account data and no output schema, the description should clarify what fields or state the returned account includes, especially the meaning of 'delivered'. The sibling tools for account management suggest there are distinct account states or types, and this description fails to contextualize its role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for parameters is 100%, with the 'id' parameter described as 'Saved account ID.' The description does not elaborate further on the parameter. Baseline 3 is appropriate since the schema already documents the single parameter sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a delivered account.' clearly indicates the action (get) and resource (a delivered account). However, it does not define what 'delivered' means in this context, which could cause confusion. It is minimally adequate but lacks specificity to distinguish from related tools like 'tokportal_get_account_managed_subscription' or 'tokportal_get_account' (if such existed).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'tokportal_get_account_managed_subscription' or 'tokportal_get_bundle_account'. The term 'delivered' is unexplained, and there are no remarks about prerequisites or contexts where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true, which the description does not contradict. The description adds minimal behavioral context—just 'drilldown' implying detailed/expanded data—but does not specify pagination, sorting, or response size limits. Since annotations already cover the safety profile, the description provides marginal additional value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that effectively communicates the action. It is front-loaded with the verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter, no output schema, and annotations providing safety cues, the description is minimal. However, given the large number of sibling analytics tools, the description lacks completeness by not clarifying what distinguishes this tool or what output to expect (e.g., 'drilldown' could mean a breakdown by metric or time period). The agent may not know when this tool is relevant.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (one parameter 'id' with format uuid and a description 'Saved account ID.'). The description does not add any extra meaning beyond the schema, so baseline 3 is appropriate. The description implies the parameter is the account identifier for the drilldown, but no new detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get account analytics drilldown' uses a specific verb ('Get') and resource ('account analytics drilldown'), which clearly indicates the tool retrieves detailed analytics data for an account. However, it does not differentiate from siblings like 'tokportal_get_account_analytics' and 'tokportal_get_analytics_dashboard', which may cover similar or overlapping information, leaving ambiguity about what 'drilldown' specifically means.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings. With many related analytics tools (e.g., 'tokportal_get_account_analytics', 'tokportal_get_analytics_series', 'tokportal_get_analytics_dashboard'), the agent lacks criteria for selection, such as which one is for aggregate data versus detailed drilldowns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat these. However, the description adds no extra behavioral context, such as whether the dashboard aggregates across accounts or platforms, or what filters affect the result. A 3 is appropriate as annotations handle safety profile but description misses useful nuance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is appropriately front-loaded. However, it is slightly under-specified given the tool's complexity (6 parameters, many siblings), warranting a 4 rather than a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should indicate what the response contains (e.g., metrics, charts, aggregated data). It also does not address the meaning of each filter parameter or how the dashboard is scoped. For a tool with 6 parameters and no output schema, this description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with each parameter having a clear description (e.g., 'Repeatable account filter.'). The tool description does not add additional meaning beyond the schema, so a baseline of 3 is correct. The description could have clarified how filters interact (e.g., AND vs OR) but that is not required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get analytics dashboard' uses a clear verb and resource, indicating the tool retrieves an analytics dashboard. However, it lacks specificity about what the dashboard contains (e.g., metrics, visualizations) and does not distinguish it from sibling tools like tokportal_get_account_analytics or tokportal_get_analytics_account, which also retrieve analytics data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as tokportal_get_analytics_series or tokportal_export_analytics_report_html. It does not specify prerequisites, expected context, or scenarios where this tool is appropriate, making it hard for an agent to decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, so the description does not need to reiterate safety. The description adds no behavioral context beyond what the annotations state. Given good annotation coverage, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single seven-word sentence. It is concise but arguably under-specified for a tool with many siblings. It does not waste words but also does not earn its place by adding value beyond the title and name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has low complexity: one required UUID parameter, strong annotations, and no output schema. The description is minimally sufficient for a simple read operation. However, it does not explain what the returned endpoint data contains (e.g., URL, events, status), which could help an agent use the result later. Still, completeness is adequate given the simplicity and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with one parameter, id, which has a clear description and format. The description adds no extra meaning beyond the schema. Since there is only one well-documented parameter, baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Get a webhook endpoint.' It is a specific verb-resource pair that is clear on its face. However, it does not distinguish itself from sibling tools like 'tokportal_list_webhook_endpoints' (which likely returns a list) or 'tokportal_test_webhook_endpoint', leaving the agent without differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool instead of alternatives. For example, the agent must decide between this tool and 'tokportal_list_webhook_endpoints' or 'tokportal_test_webhook_endpoint' without any hints. There are no usage context notes, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, informing the agent it is a safe, idempotent read operation. The description adds no further behavioral details beyond confirming the list action, which is adequate but does not provide additional context such as pagination behavior or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded. It communicates the core purpose without unnecessary words. While it is minimal, it earns its place by being direct, though it could benefit from slightly more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema, the description is incomplete. It does not explain what a 'delivered' account is, how results are ordered, or what the response looks like. The schema covers parameter descriptions but the top-level description fails to provide operational context, leaving gaps for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (page, banned, country, per_page, platform) has a description in the input schema. The top-level description adds no extra meaning or interaction hints beyond what the schema already provides, meeting the baseline for a tool with full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List delivered accounts' clearly states the verb and resource, identifying it as a list operation for a specific subset of accounts. However, it does not explain what 'delivered' means in this context, and among sibling tools like tokportal_list_bundles and tokportal_list_account_bans, there is no differentiation, making it slightly vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any context, prerequisites, exclusions, or references to sibling tools such as tokportal_get_account or tokportal_list_account_bans, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds minimal behavioral context beyond the annotations. Annotations indicate it is not read-only and not destructive, which aligns with 'update', but nothing is said about whether it performs a full replacement or partial patch, expected side effects, or response behavior. The description could elaborate on the mutation semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words of substance). While concise, it fails to structure any additional useful information. It earns a 3 because it is not verbose, but it could be improved by adding a brief sentence about the body's partial update behavior or idempotency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters including a nested object and no output schema, the description is incomplete. It does not mention what the response returns, that the 'body' fields are optional for partial updates, or the purpose of the idempotency key. More context is needed for an AI agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no extra parameter meaning beyond what the schema already provides (e.g., that 'body' is a JSON object with optional fields).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('webhook endpoint'), which is distinct from sibling tools like create or delete. However, it lacks any additional context about scope or partial updates that would elevate it to a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like creating or deleting webhooks. There is no mention of prerequisites, required state (e.g., endpoint must exist), or context for when an update is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. However, the description adds no behavioral context beyond annotations—e.g., ordering, pagination behavior, whether comments include metadata or timestamps. For a list operation, this is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words or filler. It efficiently conveys the core action and resource. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description omits any details about the return format (e.g., list of comment objects, pagination metadata, ordering). Given the number of sibling list tools and the lack of output schema, the description should compensate with a brief note on what's returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description itself does not explain parameter roles (e.g., how 'postId' and 'trackedPostId' relate). The schema descriptions are weak ('query parameter limit'), but the description adds nothing to clarify them. Acceptable but not helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'List' and resource 'comments for an account post', which is specific. However, it does not differentiate from siblings like tokportal_list_comment_tasks (lists comment tasks) or tokportal_get_comment_pulse (aggregate metrics). The term 'account post' is clear but could be more precise against similar resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., tokportal_list_analytics_post_raw_snapshots, tokportal_list_account_video_analytics). With 50+ siblings, the description should specify the use case (e.g., retrieving actual comment text vs. analytics snapshots) and any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context beyond the action of checking availability, such as what 'availability' means, whether it returns a boolean, or that it does not trigger a refresh.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero unnecessary words, perfectly concise for this simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, but the description does not clarify the return value or how this check relates to the refresh flow. It is minimally adequate but could benefit from noting that it is a pre-check and does not perform the refresh.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the id parameter described as 'Saved account ID.' The description adds no extra semantic meaning beyond this, so it meets the baseline for well-documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Check') and resource ('analytics refresh availability'), clearly indicating the tool's function. However, it does not explicitly differentiate from sibling tools like tokportal_refresh_account_analytics or tokportal_get_account_analytics, so it lacks full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that this is a pre-check before refreshing analytics, nor does it reference any sibling tools or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's simple phrase 'Get bundle account configuration' does not add significant behavioral detail. It does not contradict annotations, but also does not disclose potential error conditions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that front-loads the verb and resource. It is concise, though it could include a bit more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with no output schema and many related sibling tools (e.g., configure, finalize, list), the description is too minimal. It fails to explain what 'bundle account configuration' means or how it fits into the broader workflow, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (the only parameter 'id' has a description 'Bundle ID.'). The tool description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and the specific resource (bundle account configuration), which distinguishes it from siblings like tokportal_get_bundle (different resource) and tokportal_configure_bundle_account (write operation). However, it does not elaborate on what 'configuration' includes, slightly reducing clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as tokportal_get_bundle or tokportal_configure_bundle_account. The agent must rely solely on the tool name and context from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which indicate safe, non-mutating behavior. The description does not contradict these. However, it adds no additional behavioral context such as pagination limits, rate constraints, or what 'delivered' means operationally. With strong annotations, a 3 is appropriate—the description adds little 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with clear wording and no redundant information. It is front-loaded with the key action and resource. One could argue it is slightly under-specified (could elaborate on 'delivered'), but it earns its place without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters, no output schema, and moderate sibling complexity (tokportal_list_bundles is a close alternative). The description does not clarify pagination behavior, expected return structure, or the meaning of bundle statuses. For a list operation that likely returns a paginated list, more contextual completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional semantic meaning beyond what the schema provides (e.g., it does not explain the 'status' filter values or the relationship between 'id' and the account). Baseline 3 is correct given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('list bundles') and the target resource ('delivered account'). Among siblings, tokportal_list_bundles exists but lacks the 'for a delivered account' constraint, helping differentiate this tool's scope. However, the term 'delivered account' is not defined, and the description does not specify what 'bundles' are in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like tokportal_list_bundles (which likely lists all bundles without account filtering) or tokportal_get_bundle (for a single bundle). No exclusions, prerequisites, or context for the 'delivered account' concept are given, leaving an agent to guess the selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds no further behavioral context (e.g., pagination limits, authentication needs, or output characteristics), which is acceptable but not additive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the core purpose without redundancy. It could be slightly more informative but remains efficient for a straightforward read-only list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits important context for a tool with 5 parameters and no output schema. It doesn't mention pagination, sorting defaults, or how this differs from other analytics tools. The schema covers parameter details, but the description fails to provide overarching use-case guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions (e.g., sorting by views, likes). The tool description does not add any meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('post analytics' for an account), distinguishing from siblings like tokportal_get_account_analytics (aggregate) and tokportal_get_video_analytics (single video). However, it doesn't explicitly differentiate from similar listing tools, leaving slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., when to use raw snapshots vs aggregated analytics). No prerequisites or when-not-to-use conditions are mentioned, leaving the agent to infer context entirely from the tool name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (only readOnlyHint and destructiveHint are false), but the description provides substantial behavioral context beyond them. It details conditional starting behavior (account coverage requirements), renewal logic, and what happens if renewal fails (no task or media mutation). This is valuable for an agent understanding side effects and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise with four sentences covering key conditions and behavior. It is front-loaded with the core purpose but could be slightly more streamlined without losing important nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the publish action and coverage prerequisites but does not mention outputs or return values (no output schema). For a mutating operation like publishing a video slot, information about what is returned (e.g., success, updated entity) would improve completeness. However, given the complexity and sparse annotations, it covers the main behavioral aspects adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the three parameters (id, position, idempotency_key). The description does not add further semantic meaning or usage hints for these parameters, keeping the score at baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Publish one video slot,' which matches the title and name, providing a clear verb and resource. However, within a large family of video-related sibling tools like 'publish_all_bundle_videos' and 'configure_bundle_video,' it does not explicitly differentiate itself from similar operations, leaving the scope ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains conditions related to TokPortal Coverage and grandfathered status but does not specify when to use this tool versus alternatives like 'publish_all_bundle_videos' or 'configure_bundle_video.' It lacks guidance on prerequisites or context for selection, such as when to publish a single slot versus all slots.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations: 'readOnlyHint': true and 'destructiveHint': false confirm it's a safe read operation, and 'idempotentHint': true is consistent. The description adds minimal behavioral context (e.g., it retrieves configuration), but annotations already cover safety and idempotency, so the burden is low. No contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words: 'Get video slot configuration.' It is fully front-loaded and efficiently communicates the tool's core action. Every character earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a simple read operation, the description sufficiently covers the input (via schema) and purpose. However, it lacks any detail about return values (e.g., the structure of the configuration), which would help an agent anticipate results. For a read tool with no output schema, this is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meaning both 'id' and 'position' have descriptions in the schema. The description does not add new semantic meaning beyond the schema (e.g., 'Bundle ID' and '1-based video slot position' are already clear). A baseline of 3 is appropriate because the description provides no additional parameter insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get video slot configuration' uses a specific verb ('Get') and resource ('video slot configuration'), which clearly distinguishes it from sibling tools like tokportal_configure_bundle_video or tokportal_list_bundle_videos. However, it lacks details on what the configuration contains (e.g., properties, timing) and doesn't mention the bundle context, making it slightly vague for an API-focused agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like tokportal_list_bundle_videos (which lists slots) or tokportal_configure_bundle_video (which modifies). The description implies a read operation, but it doesn't explain prerequisites (e.g., requires a bundle ID) or post-conditions. Without exclusions or alternatives, the agent may misuse it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds meaningful behavioral context: the data is 'raw analytics payloads', 'owner-scoped', and retrieved for a 'saved account', which explains scoping beyond annotations. However, it doesn't specify pagination behavior or whether the result is a single snapshot or list (the verb suggests a list but the wording is ambiguous). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences (about 20 words) that are front-loaded with the core purpose. Every sentence adds distinct information: what the tool does, what it returns (scoping context), and an eligibility constraint. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate parameter count (5), 100% schema coverage, and no output schema, the description provides the essential constraint ('Full analytics tier only') and scoping context, but does not explain the return format or whether this is a single snapshot or a list, nor does it describe what 'raw analytics payloads' contain structurally. It is adequate but leaves the agent guessing about the output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the descriptions in the schema are minimal: 'Saved account ID' and generic 'query parameter to/from/limit/source'. The tool description does not add any parameter meaning beyond the schema, missing opportunities to explain how 'to' and 'from' define the date range, what 'source' filters mean, or how 'limit' affects the result. With 5 parameters and no enrichment, this is a gap even with full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific verb ('List') and resource ('raw account analytics snapshots'), and adds useful scoping ('owner-scoped stored raw analytics payloads for a saved account'). It distinguishes itself from likely similar siblings like 'tokportal_list_analytics_post_raw_snapshots' by referencing 'account' rather than 'post', though it doesn't explicitly compare against that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an important constraint ('Full analytics tier only') that guides when to use this tool, and implies it's for reading saved raw analytics. However, it lacks explicit guidance on when not to use it versus alternatives like `tokportal_get_account_analytics` or `tokportal_get_analytics_account`, and does not mention any prerequisites beyond the required `id` parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint: true, idempotentHint: true, and destructiveHint: false, so the agent knows this is a safe read operation. The description adds nothing beyond what annotations state, but there is no contradiction. A 3 is appropriate because the description does not add meaningful 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the relevant verb and resource. It is minimal but contains no wasted words. However, given the need for usage guidance, it could be slightly more beneficial without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, no output schema, and no nested objects. The description is sparse but combined with the schema and annotations it is minimally complete for listing items. However, it lacks any mention of what is returned (e.g., a paginated list of delivery objects) and does not clarify the relationship to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 5 parameters are described in the schema. The description does not add any additional meaning or constraints beyond what the schema provides. The baseline of 3 applies since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List webhook deliveries' uses a clear verb ('List') and specific resource ('webhook deliveries'). Among siblings, there are tools like tokportal_list_webhook_events and tokportal_list_webhook_endpoints, but the description directly distinguishes this one as listing deliveries, not endpoints or events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. Siblings include tokportal_retry_webhook_delivery and tokportal_test_webhook_endpoint, which are related but the description does not clarify that this is for viewing historical delivery records, not for retrying or testing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, which is neutral. The description adds that the tool fetches from a 'public direct image URL' and stores 'permanently,' hinting at persistence behavior. However, it does not discuss side effects (e.g., storage costs, overwrites), error conditions (e.g., invalid URL, non-image), or idempotency despite the idempotency_key parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and front-loaded with the action. It could be slightly improved by adding a brief usage guideline or parameter clarification, but currently contains no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description does not explain the return value (e.g., success indicator, image ID, URL). For a 2-parameter tool with nested body, the description covers the core action but leaves gaps in usage context and expected output. The annotations are basic, so the description carries missing behavioral detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds no new meaning beyond the schema, aligning with the baseline of 3. The 'purpose' enum has a default but the description does not clarify its role; the schema already explains it. The description's mention of 'public direct image URL' reinforces the url parameter but does not add information about idempotency_key.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Import') and resource ('image from URL'). It explains what the tool does: fetches a public direct image URL and stores it permanently in TokPortal storage. There are sibling upload tools (tokportal_upload_image, tokportal_upload_image_direct) that could overlap, but the description distinguishes this one by focusing on URL import rather than direct file upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide when to use this tool vs. alternatives like tokportal_upload_image or tokportal_upload_image_direct. No guidance on prerequisites (e.g., existence of bundle_id), when not to use, or what types of URLs are acceptable. The agent must infer usage from the parameter schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds the word 'active', which qualifies the state of the edit request being retrieved. However, it does not disclose what happens if no active request exists (e.g., returns null or an error), nor any other behavioral details. With annotations carrying most of the burden, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly states the action and resource. It contains no fluff or redundancies. A slight deduction for missing the distinction between 'account id' and 'edit request id', but overall very concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 1 simple parameter, full schema coverage, strong annotations, and no output schema, the description is minimally complete. However, it does not explain what the tool returns (e.g., the full edit request object) or how to interpret 'active'. This is adequate for a simple retrieval tool but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (1 parameter of 1 described). The schema already documents 'id' with format uuid and description 'Saved account ID.' The tool description does not add further semantics about the parameter, but with full coverage, the baseline is 3. The description's brevity is acceptable, but it could have clarified that the 'id' refers to the account, not the edit request itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get active account edit request' uses a clear verb ('Get') and specific resource ('active account edit request'), which distinguishes it from sibling tools like 'tokportal_create_account_edit_request'. The purpose is unambiguous and focused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Notably, the sibling list includes 'tokportal_create_account_edit_request' and 'tokportal_configure_bundle_account', but the description does not clarify that this tool should be used to retrieve an existing edit request rather than creating or configuring one. No exclusions or when-not conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations. It explains the dependency on a delivered saved account, the requirement for active TokPortal Coverage or permanent grandfathering, and the automatic renewal behavior. It also clarifies that if Coverage cannot renew, no task or media mutation starts. This informs the agent about side effects and edge cases. The annotations declare destructiveHint=true, which aligns with unscheduling, and readOnlyHint=false, also consistent. There is 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long. The first sentence is direct and effective. The remaining three sentences cover important preconditions but could be more tightly integrated. Some redundancy exists (e.g., 'account must have active TokPortal Coverage' and 'If Coverage cannot renew' are related). A more structured approach—perhaps a summary line followed by bullet points for conditions—would improve clarity without adding length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and the tool's complexity (dependencies on Coverage, grandfathering, renewal), the description adequately covers preconditions and edge cases. However, it does not describe the immediate result of a successful unscheduling (e.g., the video slot is removed from the bundle schedule, the bundle is updated). This missing outcome information reduces completeness for an agent that needs to understand what to expect after invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have full schema descriptions (id: 'Bundle ID.', position: '1-based video slot position.', idempotency_key: 'Optional Idempotency-Key header for safe retries.'). The tool description does not add any parameter-level detail beyond what the schema already provides. Per the scoring guidelines, high schema coverage (>80%) sets a baseline of 3, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Unschedule one video slot,' which clearly states the verb (unschedule) and resource (video slot). This is specific and distinct from siblings like 'reset_bundle_video' or 'configure_bundle_video.' However, it does not explicitly differentiate itself from these siblings, and the additional conditions about Coverage and grandfathering, while relevant, slightly dilute the core purpose. Overall, it is clear but not maximally distinctive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, nor does it reference any sibling tools such as 'tokportal_reset_bundle_video' or 'tokportal_configure_bundle_video.' The focus is entirely on preconditions (Coverage, grandfathering) rather than usage context. This leaves an AI agent to infer the appropriate scenario solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no behavioral hints (all false). The description adds only that it updates 'mutable bundle metadata' and lists fields, but does not disclose whether the update is partial or full replacement, what happens to omitted fields, error conditions, authorization requirements, or response behavior. The description adds minimal value beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences (14 words), front-loaded with the action, and contains no fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with 3 params, no output schema, and neutral annotations, the description is minimally adequate. However, it omits the partial-update behavior implied by minProperties:1, does not mention idempotency_key usage, and provides no return value information. The gaps are moderate but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already describes all parameters. The description reiterates the mutable fields (title, external_ref, auto_finalize_videos) which are already in the body property schema. This adds no new semantic meaning, but reinforces the purpose. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'bundle settings', and lists specific mutable fields (title, external_ref, auto_finalize_videos). This distinguishes it from sibling tools like tokportal_get_bundle (read) or tokportal_create_bundle (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., tokportal_create_bundle for new bundles, tokportal_publish_bundle for publishing). There is no mention of prerequisites, idempotency key usage, or when not to use this tool. This is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: the upload URL is short-lived, the response contains a secret not stored in the replay ledger, and idempotency keys are rejected with a specific error. This adds value beyond the annotations, which only set readOnlyHint=false, destructiveHint=false, idempotentHint=false. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loaded with the main purpose. Every sentence adds specific value: what it does, response contents, idempotency key restriction, and ledger behavior. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good annotation coverage and schema details, the description lacks important context: how long the URL is valid, how to use the token, any file size limits, or the purpose of the 'purpose' field. The tool returns a signed URL and token, but the description does not explain the next steps. For a tool with no output schema, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage (the 'body' parameter is described as JSON, and 'content_type' has a regex and description). However, the tool description adds no meaning about parameters—it does not mention required fields (filename, content_type, bundle_id) or the purpose enum. The schema already documents these, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and resource 'image upload URL', and mentions it returns a signed upload URL and token. However, it does not differentiate from sibling tools like tokportal_upload_image_direct or tokportal_upload_image_from_url, which could cause confusion about which to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only warns against sending an Idempotency-Key header, but provides no guidance on when to use this tool versus alternatives (e.g., direct upload, URL-based upload). There is no mention of prerequisites, typical workflow, or when to avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's a write operation (readOnlyHint=false) and non-destructive. The description adds context about the upload method (multipart) and return value (public URL), but lacks details on file size limits, format restrictions, or whether the operation overwrites existing videos. It 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey the action, method, and result. The first sentence immediately states the purpose ('Upload a video file directly'). No extraneous words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (multiple sibling upload tools, no output schema), the description is adequate but incomplete. It does not explain the relationship to tokportal_upload_video, mention any file constraints, or clarify that bundle_id is required beyond the schema. For a simple upload tool with 3 parameters, it meets minimum viability but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all three parameters adequately. The description adds no additional parameter semantics beyond what the schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Upload a video file directly') and the method ('multipart/form-data') and return value ('public video URL'). However, it does not differentiate from the sibling tool 'tokportal_upload_video' (non-direct), so some ambiguity remains about when to use this specific variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like tokportal_upload_video, tokportal_upload_image, or tokportal_upload_image_direct. There is no mention of prerequisites, conditions, or scenarios where this direct upload is preferred over indirect methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only, not idempotent, minimally intrusive (destructiveHint: false), and not open-world. The description correctly implies a mutating action. However, it does not disclose what happens to existing slots, whether the operation is additive or total replacement, or any side effects. With low annotation signal, the description misses behavioral clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that covers the core action and resource. Every word is necessary. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and three parameters (including a nested body), the description does not explain the operation's effect on the bundle, any validation errors, or return value. It is bare-minimum complete for a simple additive action, but lacks context for error cases or confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no parameter-level details beyond the schema. The schema already explains 'id' as Bundle ID and 'body' with quantity constraints. The description's brevity does not reduce clarity, but it also does not enhance it. Baseline 3 for high coverage, +1 because the nested body object and idempotency key are clear enough without further prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add video slots to a bundle' clearly states the verb (add) and the resource (video slots to a bundle). However, it does not differentiate itself from sibling tools like 'tokportal_add_edit_slots', which also adds a type of slot to a bundle. The scope is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (like creating or editing a bundle, or the similar 'tokportal_add_edit_slots'). There is no mention of prerequisites (e.g., bundle must exist), nor exclusions. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide helpful hints: destructiveHint=true, idempotentHint=true, readOnlyHint=false. The description adds no additional behavioral context beyond 'Delete a webhook endpoint'. However, with these annotations, the bar is lower, and the description doesn't contradict them. A 4 is appropriate because the annotations cover the safety profile well, and the description is consistent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded with the core action. However, it could be considered under-specified for a destructive tool (e.g., no mention of reversibility or cascading effects), so it earns a 4 rather than a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no output schema, and annotations that declare destructiveness and idempotency, the description is minimally complete. It sets expectations for what happens (deletion) but doesn't cover consequences (e.g., are related deliveries affected?), return values, or confirmation behavior. Acceptable but leaves gaps for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (id: UUID, idempotency_key: optional string) fully documented in the schema. The description adds no parameter-level detail. Per rules, baseline is 3 since schema coverage is high, and no extra value is provided in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a webhook endpoint' with a specific verb (Delete) and resource (webhook endpoint). While it differentiates from sibling tools like tokportal_create_webhook_endpoint and tokportal_get_webhook_endpoint, it doesn't clarify whether this deletes a single endpoint by ID only, which leaves a slight question about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Among siblings, there are several webhook-related tools (create, get, update, list, test), but no exclusions or context for when deletion is appropriate. No mention of prerequisites (e.g., endpoint must exist) 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which inform the agent this is a safe, non-mutating operation. The description 'Get credit balance' is consistent with these hints but adds no further behavioral context (e.g., how often the balance updates, whether caching applies). The description does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, brief sentence with no unnecessary words. It front-loads the core action and resource, making it easily parsable. Every part of the description earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and adequate for a parameterless read-only tool. However, there is no output schema, and the description does not clarify what the credit balance refers to (e.g., user account balance, platform credit pool) or the format/scope of the returned value. Given the sibling tools and lack of additional context, the description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the input schema fully covers the interface. The description adds the semantic that the tool retrieves a credit balance, which is meaningful given the empty schema. Since schema description coverage is 100% (trivially), the baseline is 3, but the description provides helpful context beyond the empty schema, warranting a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get credit balance' clearly states the verb (Get) and resource (credit balance), making the tool's purpose obvious. However, it does not differentiate itself from sibling tools like 'tokportal_get_credit_costs' or 'tokportal_list_credit_transactions', which also deal with credit information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description lacks any indication of when to use this tool versus alternatives (e.g., tokportal_get_credit_costs for costs, tokportal_list_credit_transactions for transaction history). There is no mention of prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true, idempotentHint: true, and destructiveHint: false, so the safety profile is clear. The description adds no additional behavioral traits (e.g., pagination behavior, date range interpretation, or ordering), but since annotations cover the core safety aspects, the bar is lowered. The description is acceptable but could add more context about what the list returns (e.g., ordered by date). There is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states the purpose. It is front-loaded and efficient, though it could be slightly more informative without sacrificing brevity. Every word earns its place, but adding a note about filtering by date_from/date_to could improve it while still being concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 4 parameters with 100% schema description coverage and no output schema, the description is minimally complete for a read-only list operation. However, it lacks details about return format (e.g., paginated list, field set), ordering, or edge cases (e.g., empty results). It meets the baseline but does not exceed expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters with descriptions. The tool description itself does not add any new meaning beyond the schema. According to the rubric, baseline is 3 when coverage is high, which is appropriate here. No extra value provided but no gaps either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states "List credit transactions." It identifies the verb (list) and the resource (credit transactions). However, it does not provide detail on the scope (e.g., all credit transactions for the user/account), which would help distinguish it more precisely from siblings like tokportal_get_credit_balance or tokportal_get_credit_costs, though the resource term is unique enough among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives like tokportal_get_credit_balance or tokportal_get_credit_costs. The description does not mention typical use cases, prerequisites, or whether it is for retrieving history versus balances. The agent must infer usage solely from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds value by disclosing specific blocked states (revealed/detached, banned, inactive-Coverage) and grandfathering exceptions, which are not in annotations. However, it does not explain side effects, return behavior, or permission requirements, so the bar is only partially met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (three sentences) but contains redundancy: the first sentence 'Refresh analytics account' restates the title. The second and third sentences provide useful information but could be merged. The structure is acceptable but not optimally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain what the refresh returns or accomplishes, but it does not. It also omits prerequisites (e.g., user must own the account, account must exist) and fails to clarify the role of the nested body parameters. Given the moderate complexity (3 params, nested body, conditions), the description leaves significant gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to repeat parameter details. The description adds no additional meaning beyond the schema; it does not explain the purpose of body fields like 'force', 'postLimit', or 'idempotency_key'. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Refresh' and the resource 'analytics account', and specifies it is owner-scoped and uses Analytics v2. This distinguishes it from sibling tools like 'tokportal_can_refresh_account_analytics' (eligibility check) and 'tokportal_get_analytics_account' (read-only). The blocked conditions further clarify scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some context by listing blocked account states (revealed/detached, banned, inactive-Coverage) and eligibility of grandfathered accounts, which implicitly advises when the tool may fail. However, it does not explicitly differentiate between the two similar refresh tools ('tokportal_refresh_analytics_account' vs 'tokportal_refresh_account_analytics') or suggest when to use the 'can_refresh' check first. Guidance is present but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint: true (the idempotency key supports safe retries), readOnlyHint: false, destructiveHint: false. The description adds behavioral context about Coverage preflight, renewal, and conditional execution ('If Coverage cannot renew, no task or media mutation starts'), which complements annotations. However, it doesn't fully detail side effects like credit costs for premium features like instant_repost_as_story.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each adding distinct information: bulk config, Coverage preflight, Coverage/grandfather requirement, and auto-renewal with fallback. It is efficient but could be slightly more structured (e.g., bullet points for prerequisites). The title repeats the first line but that's fine.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested objects, 30+ sub-properties, premium features, daily limits) and no output schema, the description is incomplete. It covers Coverage and renewal but omits details like VIDEOS_PER_DAY_EXCEEDED, credit costs for paid features (instant_repost_as_story), and the 'position' element's significance. An agent would need to infer these from the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by mentioning 'account-level Coverage preflight' and auto-renewal, which provide context for the 'body' parameter. It also implies the need for an existing bundle ('Bundle ID' in id description). This goes beyond the schema's parameter descriptions, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Configure video slots in bulk' and explains it configures several slots after one account-level Coverage preflight. While the purpose is clear, it doesn't explicitly differentiate from sibling tools like tokportal_configure_bundle_video (single video slot) or tokportal_add_video_slots, but the bulk nature is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context, mentioning requirements for active TokPortal Coverage or being grandfathered, and auto-renewal behavior. However, it does not explicitly state when to use this tool versus alternatives like tokportal_configure_bundle_video for single slots or the per-bundle limits (max 500 videos, max 3 per day). No 'when not to use' guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), not idempotent, and not destructive. The description adds the behavioral detail that the tool 'approves' and 'marks finalized,' which confirms a state transition. However, it lacks disclosure of side effects (e.g., whether changes are reversible, permission requirements, or downstream impacts). For a simple mutation with decent annotations, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences totaling 15 words. The first sentence immediately states the purpose, and the second adds the key action detail. No filler or redundancy. It is as concise as possible while conveying the essential function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no nested objects), the description covers the basic action. However, it omits important context such as the required state of the account (must be in-review), potential errors, or what the return value indicates (success/failure). For a tool with no output schema, describing the outcome would improve completeness. Still, it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both id and idempotency_key have descriptions). The description does not elaborate on parameter meaning beyond the schema. It mentions 'Bundle ID' but no added context. Baseline 3 applies since the schema already documents parameters sufficiently, and the description adds no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Finalize account review. Approves an in-review account and marks it finalized.' The verb 'finalize' and the resource 'account review' are specific, distinguishing this from sibling tools like 'configure_bundle_account' or 'get_bundle_account'. The mention of 'in-review' further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., request_corrections, configure). It does not specify prerequisites (e.g., account must be in 'in-review' state), call order, or what happens if called on an already finalized account. Given many sibling tools in the account domain, this omission limits the description's helpfulness for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds no additional behavioral details beyond stating the action. With annotations carrying the burden, a score of 3 is appropriate as the description does not contradict them and remains neutral.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of four words, front-loading the action and resource. It contains zero waste and efficiently conveys the core purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single parameter, simple list operation, no output schema), the description is minimally adequate but leaves ambiguity about the return structure. It does not clarify what a 'video slot' is or that the output is an array. The agent may need to infer from sibling tools like tokportal_add_video_slots. Additional detail on the return type would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the only parameter 'id' is described as 'Bundle ID.'). The tool description does not add any extra meaning beyond the schema. Per guidelines, baseline 3 is correct when schema already documents parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List bundle video slots' uses a specific verb (List) and resource (bundle video slots), clearly indicating it returns a list of video slots for a bundle. It distinguishes from siblings like tokportal_list_bundles (lists bundles) and tokportal_get_bundle_video (gets a single video), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or specify that it requires an existing bundle ID. An agent must infer usage from the tool name and sibling context, which is insufficient for clear decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond the annotations, such as whether the list is static or dynamic, or any side effects. It essentially restates the title.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, making it concise and front-loaded. However, it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not explain what the returned list contains (e.g., country codes, names, objects). For a simple list tool, the agent would benefit from knowing the format or structure of the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is fully covered. The description does not need to add parameter semantics. Baseline for no parameters is 4, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List available countries' uses a specific verb ('list') and resource ('countries'), clearly distinguishing it from sibling tools like 'list_platforms' or 'list_bundles'. It leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives such as 'list_platforms'. It implies that this tool is for obtaining a list of countries, but does not provide context like prerequisites, filtering, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no behavioral context beyond what the name and annotations provide—it doesn't mention pagination behavior, ordering, rate limits, or scoping (e.g., which account's endpoints?). Since annotations cover the safety profile, a baseline of 3 is appropriate; the description contributes no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three words—'List webhook endpoints.'—with zero wasted text. Every word earns its place, and the entire purpose is front-loaded. This is an ideal length for a tool with good schema coverage and annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 4 optional parameters and no output schema, the description is adequate but minimal. It does not explain what happens if no endpoints exist, whether results are scoped to a specific account (given openWorldHint=false), or the ordering of results. The combination of annotations and schema covers safety and parameter details, so completeness is acceptable but could be improved with scoping context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all 4 parameters (page, event, enabled, per_page) with clear types, defaults, constraints, and descriptions. The tool description offers no additional parameter information, so it does not add meaning beyond the schema. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description "List webhook endpoints" uses a specific verb (list) and resource (webhook endpoints). It clearly distinguishes this from sibling tools like get_webhook_endpoint (singular), create/update/delete, and list_webhook_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention that list_webhook_endpoints retrieves all endpoints while get_webhook_endpoint retrieves a single one, nor does it advise on pagination or filtering. The agent has no context for choosing this over other list/read operations among 56 siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations set readOnlyHint=false and destructiveHint=false, which the description complements by explaining that patching may be blocked if coverage cannot renew, revealing a conditional behavior. This adds value beyond annotations, though more details on rollback or error states would be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of 4 sentences. It is not overly verbose but could benefit from being more front-loaded; the first sentence suffice for purpose, but the second and third sentences about coverage are specific and earn their place. It is adequate but not exceptionally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and a nested body object, the description covers the critical coverage constraint but omits details on response behavior or what happens if validation fails. It is complete enough for basic use but lacks depth for troubleshooting or advanced workflows.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter hints (e.g., maxLength, pattern, enum-like constraints). The description adds no new meaning to parameters, so baseline 3 is appropriate. It does not enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it patches video metadata or schedule, distinguishing it from siblings like 'tokportal_publish_bundle_video' or 'tokportal_unschedule_bundle_video'. However, the initial phrasing is generic and does not fully differentiate from 'tokportal_configure_bundle_video' which also modifies videos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about coverage and renewal conditions but does not explain when to use this tool versus alternatives like 'tokportal_configure_bundle_video' or 'tokportal_finalize_bundle_video'. The coverage condition is helpful but no explicit when-not or alternative guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it explains that the tool may start a task or media mutation, details the dependency on coverage renewal, and clarifies that no mutation occurs if renewal fails. Annotations only provide readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the description meaningfully enriches the agent's understanding of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences, front-loaded with the core purpose. It wastes no words. However, the structure could be improved by separating the condition from the main action, but it remains efficient for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, nested objects, and no output schema, the description is incomplete. It does not explain what the correction request returns, how to interpret the boolean fields, or the workflow after requesting corrections. The focus on coverage conditions leaves out essential operational details for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema: it mentions the bundle state condition but does not elaborate on the meaning of the fields (sound, description, video_content, video_editing) or the relationship between body and the top-level fields/comment. The parameter syntax is already clear from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Request video corrections' which identifies the verb and resource. The name distinguishes it from 'tokportal_request_bundle_account_corrections' but does not differentiate it from other video manipulation tools like 'tokportal_configure_bundle_video' or 'tokportal_patch_bundle_video', leaving ambiguity about when exactly to request corrections vs. configure or patch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides conditions for use (bundle must resolve to a delivered saved account with active TokPortal Coverage or grandfathered status, renewal behavior, and fallback if coverage cannot renew). However, it does not explicitly state when to use this tool over alternatives or when not to use it, lacking explicit guidance for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the specific behavior that HEIF/HEIC files may be converted to JPEG, which is beyond the annotations. However, it omits other behavioral traits such as whether uploads are synchronous, whether existing files are overwritten, or any authentication or file size constraints. With sparse annotations (no readOnlyHint or destructiveHint), the description carries moderate burden but provides minimal 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that deliver the core purpose and a critical behavioral note. Every word earns its place, with no redundancy or filler. It is front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 'returns storage details' but does not specify what those details are (e.g., URL, ID, dimensions). It also lacks constraints like max file size or accepted formats beyond the HEIF note. For a tool with four parameters and no output schema, the description is somewhat incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters are already described in the schema. The description only adds that the upload is multipart/form-data, which is implied by the schema's parameter names. No meaning is added beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Upload', the resource 'image file', and the method 'multipart/form-data directly through TokPortal'. It also mentions a key behavioral detail about HEIF/HEIC conversion, distinguishing it from sibling tools like tokportal_upload_image_from_url. The title reinforces this purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus the alternative upload tools (e.g., tokportal_upload_image, tokportal_upload_image_from_url). It only says 'directly' but lacks explicit when-to-use or when-not-to-use advice. Given the large sibling list with similar upload functions, this omission is significant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only set readOnlyHint=false, destuctiveHint=false, idempotentHint=false), the description discloses important behavioral traits: the presigned URL is short-lived, the response contains a secret that is not stored in the replay ledger, and sending an Idempotency-Key triggers a 400 error before any execution. This significantly clarifies the tool's side effects and safety profile. Slightly held back by omitting the response structure, but still strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, no wasted words. It front-loads the purpose in the first sentence, then adds essential constraints and error behavior. Every sentence earns its place by providing critical operational details (short-lived URL, idempotency prohibition, security note). Exceptionally concise for the depth of information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single parameter (a nested object with three fields) and no output schema, the description could do more. It omits the response structure (e.g., what fields are returned—upload_url, expiry, etc.). It also does not mention prerequisites (the bundle must exist before its ID is used). The behavioral notes are helpful, but these gaps reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is reported as 100%, meaning the schema already provides descriptions for all parameters (the `body` parameter has description 'JSON request body.'). The description adds no additional meaning about the parameters (filename, bundle_id, content_type). With high schema coverage, the baseline is 3, and the description does not elevate beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the core purpose clearly: 'Create a video upload URL' and 'Returns a short-lived presigned upload capability.' However, it does not differentiate from the sibling tool `tokportal_upload_video_direct`, which likely performs a direct upload instead of generating a URL. This lack of explicit contrast prevents a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides only one usage constraint: 'Do not send Idempotency-Key.' It gives no guidance on when to use this tool versus alternatives (e.g., `tokportal_upload_video_direct` for direct uploads, or other upload tools). There are no context clues about prerequisites (e.g., needing a bundle_id from a previously created bundle) or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations providing only empty hints (all false), the description adds useful behavioral details like coverage prerequisites, automatic renewal, and the condition that no mutation occurs if coverage fails. However, it fails to describe the return value or what happens on success, leaving a gap in transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with the core purpose and then adding necessary conditional details. It is not overly verbose, though the conditional block could be slightly better structured for readability. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 params, nested objects, and no output schema, the description covers the core behavior and key prerequisites but omits the return value, error conditions, and the full workflow (e.g., what 'task' it triggers). This leaves the agent with incomplete understanding for a complex mutable operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already described. The description mentions 'manager-flagged broken video or carousel download URL' which indirectly explains the body parameter's purpose, but does not clarify the mutual exclusivity of video_url and carousel_images or add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fixes a broken video download by replacing a manager-flagged broken URL and clearing the issue flag. This specific verb+resource combination distinguishes it from sibling tools like tokportal_configure_bundle_video or tokportal_patch_bundle_video which handle other video modifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about required account coverage and automatic renewal behavior, but does not explicitly state when to use this tool over alternatives or when not to use it. It implies usage for flagged broken downloads but lacks comparative guidance against tools like tokportal_reset_bundle_video.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false and no destructiveHint or idempotentHint, so the description carries the burden—it does well by explaining coverage checks, auto-renewal behavior, and conditional execution. This goes 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, conveying key behavioral details in 5 sentences. It front-loads the primary action and then covers conditions. However, it could trim some redundancy (e.g., 'or be permanently grandfathered' is detailed but optional).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description doesn't clarify what the tool returns or confirm success/failure indicators. The parameter documentation is sufficient, and the behavioral details are good, but the lack of return value description leaves a gap for an AI agent to understand the outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description adds no parameter-specific details beyond the schema, which is expected at this coverage level. The description gives high-level context but doesn't elaborate on parameters like id or file_path further, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool imports video slots from CSV and performs multiple related actions (uploads, downloads, configures). It distinguishes itself from sibling tools like tokportal_add_video_slots or tokportal_configure_bundle_video, though it doesn't explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains important usage context, such as coverage checking and account requirements, but does not explicitly state when to use this tool versus alternatives like tokportal_add_video_slots or tokportal_batch_configure_bundle_videos. The coverage renewal details are helpful but no direct sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what the annotations already provide (readOnlyHint=true, idempotentHint=true, destructiveHint=false). It simply restates the operation without disclosing any additional traits such as rate limits, authentication requirements, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at three words, with no wasted content. The information is front-loaded and immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with no parameters and good annotations, the description is minimally adequate. However, it lacks any indication of what the response contains (e.g., user object fields), which would be helpful since there is no output schema. This gap reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema coverage, so the description carries no responsibility to explain them. Baseline for no parameters is 4, and the description does not detract from that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get authenticated user' is a specific verb+resource combination that clearly indicates the tool retrieves the currently authenticated user. It is unambiguous and distinguishes itself from sibling tools like 'tokportal_get_account' which retrieves a specific account by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. The context implies it is for the current user's info, but there is no mention of when not to use it or comparisons to similar tools like 'tokportal_get_account'. Usage is left to the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds valuable behavioral context beyond annotations: it mentions that execution_blocked and execution_block_reason identify tasks paused by inactive TokPortal Coverage, and that reads remain available while execution is paused. This is useful detail that annotations do not capture, and it does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at three sentences, with the most critical information (purpose) front-loaded. The second and third sentences add specific behavioral context about execution_blocked fields without being verbose. It earns its length, though the first sentence repeats the tool's name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description provides enough context for an agent to understand the purpose (listing owned tasks) and key state information (execution_blocked, execution_block_reason). For a read-only, idempotent list operation with 4 fully described parameters, this is reasonably complete. It could hint at filtering semantics (e.g., how saved_account_id interacts with owned tasks) but is not critically incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all four parameters (page, status, per_page, saved_account_id) with their types, defaults, and constraints. The description adds no additional meaning beyond the schema—it does not explain how status filtering works (e.g., comma-separated list format is already in schema), nor does it clarify the relationship between parameters. Baseline 3 is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List comment tasks' and further specifies 'Lists owned comment tasks.' This provides a specific verb (list) and resource (owned comment tasks), distinguishing it from sibling tools like tokportal_get_comment_task (single task) and tokportal_create_comment_tasks (creation). However, it doesn't explicitly differentiate from other list tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about execution_blocked and execution_block_reason fields for paused tasks, but it does not give explicit guidance on when to use this tool versus alternatives (e.g., when to use list_comment_tasks vs get_comment_task). It implies usage for listing owned tasks but lacks exclusion criteria or alternative selection hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only (readOnlyHint: false), which aligns with the description of a publish action. The description adds valuable behavioral insight: the tool may auto-renew coverage, conditionally mutates media, and will abort if renewal fails. This goes well beyond the raw annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with four focused sentences that each add information: what it does, prerequisites, auto-renewal behavior, and fallback. No unnecessary filler. It could be slightly more front-loaded with the core action, but it works well.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers prerequisites and side effects well, but given the lack of output schema and the complexity of the operation, it would benefit from mentioning the return value (e.g., job ID, status) or whether it's async. The 100% schema coverage compensates partially, but the behavioral complexity suggests more detail would be useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are documented in the schema. The description does not elaborate further on parameters, which is acceptable given full schema coverage. However, it could add value by explaining how idempotency_key interacts with the auto-renewal behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it publishes all configured videos on an active bundle. This distinguishes it from sibling tools like tokportal_publish_bundle (which likely publishes the bundle itself) and tokportal_publish_bundle_video (single video). The action is specific and well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides important usage context about coverage requirements and auto-renewal behavior, but it does not explicitly say when to use this tool versus alternatives like tokportal_publish_bundle_video or tokportal_finalize_bundle_video. The coverage conditions are helpful but not directly comparative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it sends a signed event and records the result, providing minor behavioral context. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, front-loaded with the main action, and no superfluous words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description mentions 'records the delivery result' but does not specify whether the result is returned directly or must be retrieved later via list_webhook_deliveries. It also does not address asynchronous behavior or endpoint prerequisites, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are well-described in the schema. The description does not add any additional meaning or usage details beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Send a test webhook') and elaborates with specifics: sends a signed webhook.test event and records the delivery result. This distinguishes it from sibling webhook tools like creation, deletion, listing, or retrying deliveries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for testing an existing endpoint, but it does not explicitly state when to use it versus alternatives like retry_webhook_delivery or list_webhook_deliveries. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it as read-only, idempotent, and non-destructive. The description adds value by detailing the return content (coverage blockage status and stable block reason), providing behavioral context beyond the annotations. No contradictions exist, and the description enhances understanding of what the operation reveals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core purpose and then adding specific return details. Every sentence is informative, with no wasted words. It is appropriately sized for a simple read operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one required parameter and no output schema, the description covers the purpose, scope (owned comment task), and key output fields (coverage blockage and stable block reason). It lacks mention of error handling or what happens if the task is not found, but overall it is sufficiently complete given low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'id' (described as 'Comment task ID.'). The description adds no further explanation of the parameter, so it meets the baseline of 3 for high coverage, but does not provide additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'Get a comment task' operation with specific details about what is returned: 'one owned comment task, including whether inactive TokPortal Coverage currently blocks manager execution and the stable block reason.' This effectively distinguishes it from sibling tools like list, create, delete, etc., which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., tokportal_list_comment_tasks for multiple tasks, or tokportal_approve_comment_task for actions). It lacks any when-to-use or when-not-to-use context, leaving the agent to infer usage solely from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=false and readOnlyHint=false, which is consistent with a refresh (mutation) operation. The description adds value by detailing eligibility conditions (blocked states for certain account types) and mentioning backward-compatibility, which helps the agent understand behavioral constraints. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief with three sentences, front-loading the main action. Each sentence adds distinct value: purpose, backward-compatibility, and eligibility conditions. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 does not mention what the tool returns (e.g., success indication, updated analytics data). It covers input constraints well but omits return behavior. For a complex tool with nested body parameters and multiple options, the description is moderately complete but has a clear gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters and their defaults. The description adds no parameter-level detail beyond listing 'forced refresh and post import options', which are ambiguous references to parameters like 'force', 'includePosts', etc. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool refreshes account analytics, which aligns with the title. It adds specific context about being backward-compatible and supporting forced refresh and post import options. However, it does not explicitly distinguish itself from the sibling tool 'tokportal_refresh_analytics_account', whose purpose appears similar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when refresh is blocked (revealed/detached, banned, or inactive-Coverage accounts) and notes that permanently grandfathered accounts remain eligible. This provides clear context for when to use the tool. However, it does not mention when to use this versus the similar sibling 'tokportal_refresh_analytics_account'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (readOnlyHint=false, destructiveHint=false), so the description carries the burden of explaining the mutation. It effectively discloses that the tool transitions an account from 'in-review' to 'pending corrections' and involves reviewer feedback. This adds valuable behavioral context beyond the annotations. However, it does not mention prerequisites (e.g., account must be in 'in-review' status), potential side effects, or authorization requirements, which would make it more complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences with no redundant information. The first sentence restates the title but is acceptable. The key behavioral detail (state transition) is front-loaded in the second sentence. Every word earns its place. Could be slightly improved by merging the two sentences, but overall it is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, nested objects, anyOf constraints, no output schema), the description provides the high-level purpose and state change but lacks guidance on parameter usage, such as how to specify which fields need correction or the interplay between 'body' and 'comment' parameters. The 100% schema coverage mitigates this gap, but the description alone does not fully prepare an agent to invoke the tool correctly without deep schema parsing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all parameters described in the schema (e.g., 'Bundle ID.', 'JSON request body.'). The tool description adds no additional meaning about parameters—it does not explain the anyOf structure, the required comment inside body, or the purpose of the nested 'fields' object. Per guidelines, with high coverage, the baseline is 3, and the description does not exceed that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Request account corrections') and specifies the state transition ('Moves an in-review account back to pending corrections with reviewer feedback'). This provides a specific verb+resource+scope, and it differentiates from siblings like tokportal_request_bundle_video_corrections (which targets videos) and tokportal_finalize_bundle_account (which finalizes). The purpose is unambiguous and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when an account is in review and corrections are needed), but it provides no explicit guidance on when not to use it or how it compares to alternatives like tokportal_finalize_bundle_account or tokportal_configure_bundle_account. No alternative tools are mentioned. The usage context is inferred from the state description but lacks clear boundaries or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, which the description supports by explaining conditions under which 'no task or media mutation starts.' The description adds detail beyond annotations: it discloses the renewal behavior, inheritance of stored rate, and what happens if Coverage cannot renew. This provides good safety context for a mutation tool without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and front-loads the primary action logically. Each sentence earns its place: first states the action, second covers prerequisites, third explains the renewal behavior and fallback. The only minor inefficiency is the specific technical phrasing ('bundle resolves to a delivered saved account') which could be condensed without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters with full schema coverage, no output schema, and clear destructive annotations, the description is largely complete. It explains the precondition, the automatic renewal mechanism, and the fallback no-op. The only gap is the lack of clarifying what happens after a successful reset (e.g., any confirmation or next steps), but the tool's context within a bundle workflow makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all three parameters documented (id, position, idempotency_key). The description adds business logic around the 'position' parameter by clarifying it refers to a 'video slot,' and hints at the state machine (resolved bundle, active period). The idempotency_key parameter is mentioned in the description implicitly through the safe-retry context, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state the tool resets one video slot. The description provides context about when the bundle resolves to a delivered saved account, which adds meaning. It is distinct from siblings like tokportal_configure_bundle_video or tokportal_finalize_bundle_video, though the specific effect of 'reset' versus other video operations (e.g., configure, patch, unschedule) could be sharper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains prerequisites (active TokPortal Coverage or permanently grandfathered) and the automatic renewal behavior. However, it does not explicitly state when to use this tool versus alternatives like tokportal_configure_bundle_video for modifying slots, or tokportal_finalize_bundle_video for completion steps. The usage context is implied but lacks direct comparisons or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits: the signing secret is returned once and never stored in the replay ledger, and requests with Idempotency-Key header are rejected with a specific error code. This adds value beyond the annotations (which only indicate non-readOnly, non-idempotent, etc.) and prepares the agent for side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 sentences) and front-loaded with the purpose. It avoids unnecessary detail, but the first sentence is slightly redundant ('Create a webhook endpoint. Creates a webhook endpoint...'). Minor redundancy aside, it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description compensates by explaining the response contains a secret and that it's never stored. It also provides a post-creation step (store the secret). The behavioral aspects (idempotency key rejection) are covered. Missing details like response structure beyond the secret are not critical, but the description is sufficient for a creation tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100% (the single 'body' parameter has a description), so the baseline is 3. The tool description does not add any additional meaning to the parameters (e.g., clarifying the 'url' or 'events' fields), relying entirely on the schema. While adequate, it does not go beyond the structured data.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'webhook endpoint', and further specifies that it returns a signing secret. This distinguishes it from other webhook-related tools (list, get, update, delete) and provides a precise scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes important usage constraints like 'Do not send Idempotency-Key' and 'Store the secret to verify TokPortal webhook signatures', but it does not explicitly compare this tool to alternatives (e.g., when to use this vs. update or list endpoints). The context of creation is implicit, but with many sibling webhook tools, explicit guidance would improve score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description correctly aligns with a safe, read-only operation. The description adds value by specifying the exact payload structure (contract, access, metrics semantics, etc.), which goes 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise — two sentences providing the core action and then a simple list of return components. Every piece adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and clear annotations, the description adequately covers the tool's purpose. It explains what the contract contains, which is sufficient for an agent to decide when to use it. Could be improved by hinting at whether this is a prerequisite for other analytics operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters with 100% coverage. The description explains the tool returns a contract object, which aligns with parameterless behavior (no input needed). The description semantically adds that this is a metadata lookup, not requiring any arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns an 'analytics data contract' and lists specific components (metrics semantics, freshness targets, redaction rules). However, it could better distinguish from sibling tools like 'tokportal_get_analytics_dashboard' or 'tokportal_get_analytics_account', which also deal with analytics data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving the structural contract of analytics data, not the actual data itself. However, it does not explicitly state when to use this versus other analytics tools (e.g., for understanding data model vs. fetching metrics). No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is clear. The description adds meaningful context: it returns 'stored raw analytics payloads' (indicating actual payload data, not just metadata), and the tier constraint. No contradiction. Could elaborate on response structure or pagination, but overall adds 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words. Front-loaded with the primary action. Every sentence earns its place: listing action, scope/return value, tier requirement. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters (including optional date range, limit, source) and no output schema, the description is somewhat minimal. It doesn't explain optional parameter behavior (e.g., default date range, limit default 5 up to 30, source meaning), response structure (list with timestamps and payloads), or ordering/pagination. The schema covers parameter descriptions, but functional completeness is lacking for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no parameter-specific information beyond what the schema provides (e.g., id is 'Tracked post ID', to/from are date-time, etc.). No additional clarification or usage hints for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'raw post analytics snapshots', and adds specifics: 'Returns owner-scoped stored raw analytics payloads for a tracked post. Full analytics tier only.' This distinguishes it from sibling tools like 'list_analytics_account_raw_snapshots' by scoping to 'post' vs 'account'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage constraint: 'Full analytics tier only.' and indicates owner-scoping, but no explicit guidance on when to use this tool versus alternatives (e.g., account-level snapshots) or when not to use it. The differentiation from siblings is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behaviors beyond annotations: story screenshot verification, repost credit cost, coverage conditions, auto-renewal, and what happens if coverage cannot renew. Annotations indicate idempotentHint=true and non-destructive, which is consistent. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph of about 8 sentences. It front-loads the main purpose but could be more structured (e.g., bullet points for conditions) to improve scanability. It adequately conveys information but is not concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the nested object, numerous optional properties, and business rules (coverage, stories, credits), the description covers key constraints and conditions. It does not mention success/error response format, but no output schema is present so this is acceptable. The description is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds contextual meaning for overall behavior (e.g., story constraints, credit costs) but does not provide additional per-parameter semantics beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Configure' and the resource 'a video slot', specifying it can be configured as video, carousel, or story. This distinguishes it from siblings like tokportal_add_video_slots (which adds slots) and tokportal_patch_bundle_video (which patches an existing video configuration).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, including specific rules for stories (single video/image, no description, screenshot verification), credit costs for reposts, and coverage requirements for delivered accounts. It does not explicitly exclude alternatives like patch_bundle_video but implies this is for initial configuration or full replacement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false, but the description adds substantial behavioral context: the one-shot nature, the post-configuration lack of change, the account status conditions, warming session start triggers, TokPortal Coverage requirements, renewal behavior, and the fallback if coverage cannot renew. This goes well beyond the annotations, though the density of edge cases could be clearer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose but then expands into multiple conditional behaviors and edge cases, making it lengthy. While every sentence adds value, the structure could be more compact (e.g., bullet points or clearer separation of prerequisites vs. post-conditions). It is informative but not optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description covers key contextual aspects: prerequisites (count-only purchase), constraints (exact count, one-shot), behavior under various account statuses, and renewal conditions. It adequately informs an agent when to invoke and what to expect, though some technical details (e.g., the exact RTU mechanism) are left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reiterates the exact count and length constraints already in the schema and does not add new parameter-level semantics beyond what the schema provides. It does not clarify the idempotency_key or body wrapper beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool configures niche targets for a count-only Advanced Niche Warming purchase, specifies deferred configuration after creation, and distinguishes itself from PUT /bundles/{id}/account by noting it works at any account status. The verb 'configure' and the resource 'bundle warming terms' are specific, and the differentiation from a sibling tool is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains exactly when to use this tool: for a bundle created with advanced_warming_terms_count, requiring the exact purchased number of targets, and being a one-shot operation. It contrasts with another endpoint (PUT /bundles/{id}/account) but does not explicitly list all alternatives or state when not to use it beyond the implied scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly discloses behaviors not covered by annotations: atomicity of assignment/debit/task creation, credit cost (8 credits), manager routing logic, eligibility rules for completed bundles, and that an unavailable manager never costs credits. This far exceeds the minimal annotation set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is six sentences, front-loaded with the primary purpose. Every sentence adds value (credit cost, prerequisites, routing, atomicity, task placement). It is concise but slightly dense, losing a point for minor readability overhead.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description does not explicitly state the response structure (e.g., returns task ID or success status). While it explains side effects and atomicity, the absence of return value information leaves the agent partially in the dark about what to expect after invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions (e.g., 'Saved account ID', 'JSON request body'). The tool description adds no parameter-specific meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Request profile edits for a delivered account', a specific verb+resource statement. It further clarifies the action by noting it debits 8 credits and creates a task, effectively distinguishing it from sibling read tools like tokportal_get_account_edit_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions required prerequisites ('Active TokPortal Coverage and a routable active account manager') but does not contrast this tool with alternatives. It implies use for profile edits but provides no when-not-to-use guidance or explicit sibling differentiation beyond the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: it warns against sending Idempotency-Key, explains the sensitive nature of the response (secret, not stored in ledger), and details the rejection behavior (400 error). This is valuable for a non-idempotent, potentially destructive operation. However, it does not mention required permissions or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) with no tautology or fluff. It is front-loaded with the purpose and each sentence adds critical information: what it creates, what it returns, idempotency key warning, and rejection behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a complex nested parameter (11 properties) and no output schema, the description covers the key behavioral aspects (return value, idempotency key rejection) but does not describe the full response structure or provide usage examples. It is adequate for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters well-documented in the schema (types, formats, maxLength, etc.). The description adds no additional meaning to the parameters (e.g., does not explain the purpose of 'brandName' or 'countries'). Baseline 3 is appropriate since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an analytics web report and returns a bearer-like access token and URL. It specifies the verb 'create' and resource 'analytics web report', distinguishing it from sibling tools like tokportal_get_analytics_dashboard and tokportal_export_analytics_report_html.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises against sending an Idempotency-Key but does not explicitly state when to use this tool versus alternative analytics tools (e.g., tokportal_get_analytics_dashboard for viewing reports, tokportal_export_analytics_report_html for exports). Usage context is implied by the purpose but not explicitly differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: the `code` field is null until status is `in_review` or `finalized`. This explains state transitions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, efficient sentences. It front-loads the purpose ('Get / poll the ad code for a video') and then adds necessary behavior details. No superfluous words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description covers the core behavior (polling, null code, statuses). It does not mention error cases or rate limits, but given the annotations and simplicity, it is largely complete. Missing slight detail on whether multiple requests exist (says 'latest').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single required parameter (id, UUID) has a description 'Video ID.' in the schema. The tool description adds no further meaning to this parameter, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get / poll the ad code for a video', specifying the verb (get/poll) and resource (ad code request for a video). It distinguishes this from the sibling create tool (tokportal_create_video_ad_code_request) by being the read/poll version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for polling ad code by explaining the code field's null behavior. However, it does not explicitly state when to use this tool versus alternatives like the create counterpart or other video-related tools. No exclusions or contextual triggers are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 value by noting the tool's availability during a coverage pause, which is beyond the annotations. It does not disclose auth requirements or output format, but the annotations carry the safety burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a clear purpose: stating the action, clarifying the scope, and providing a special availability note. No unnecessary words, front-loaded with the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and rich annotations, the description is largely complete. It covers purpose, scope, and a unique availability trait. Missing details like the output structure are acceptable given no output schema and the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter 'id' with 100% description coverage ('Comment task ID'). The description adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and the resource ('comment task verification events'), and specifies it lists 'verifier attempts for one owned task'. This distinguishes it from sibling tools like get_comment_task or list_comment_tasks, which operate on different aspects of tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a contextual condition: 'This read remains available while TokPortal Coverage pauses task execution.' This hints at a specific use case but does not explicitly compare with alternatives (e.g., when to use this vs. get_comment_task) or state 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the primary behavioral traits (safe, non-mutating, idempotent). The description adds nothing beyond these annotations; it does not specify return format, pagination, or what constitutes a 'platform'. With annotations carrying the burden, a score of 3 is appropriate – the description does not contradict annotations and is consistent, but lacks extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence: 'List available platforms.' It is appropriately sized for the simplicity of the tool, contains no fluff, and front-loads the key action and resource. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters, no output schema, and annotations provide safety traits, the description is largely complete. It tells the agent what the tool does. However, a brief note on what the return value includes (e.g., 'Returns a list of platform objects with IDs and names') would improve completeness slightly. Still, for a simple list tool, this is near-complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% by default. Per the rubric, baseline score is 4. The description does not need to add parameter-level detail, and it does not misrepresent anything. No improvement needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List available platforms' uses a specific verb ('list') and a distinct resource ('platforms'), which clearly differentiates it from sibling tools that list other resources like countries, bundles, accounts, etc. The purpose is unambiguous and effectively informs the agent what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool vs alternatives. However, given the tool's simplicity (zero parameters, simple enumeration), the usage context is largely implied: it should be used when the agent needs to know which platforms are available. No misleading guidance exists, but explicit when/when-not information is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important side effects: the renewal of coverage and that no task/media mutation starts if renewal fails. This adds context beyond the annotations (which are minimal and not contradictory). It does not contradict any annotation values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, efficiently packing purpose and conditions. It is well-organized with the main action first. While clear, it could be slightly more structured with line breaks, but remains concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key conditions and side effects, but lacks output semantics (no output schema exists). It does not explain what success looks like (e.g., status changes), mention idempotency key usage, or reference the companion tool for readiness checking. For a publication procedure, this leaves moderate gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both parameters (id, idempotency_key) have descriptions. The description adds no information about parameters, so it meets the baseline but offers no extra value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool publishes a bundle, using a specific verb and resource. Among sibling tools like unpublish_bundle and publish_bundle_video, it is unambiguous which action this performs at the bundle level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains prerequisites (fully configured bundle, active TokPortal Coverage or grandfathering) and describes automatic renewal behavior. However, it does not explicitly guide the agent to alternatives like tokportal_get_bundle_publish_readiness or other publish-related tools, lacking a clear 'when-not-to-use' with sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context: it reseeds the stored payload, applies a fresh signature, and preserves the event ID for receiver-side idempotency. This goes beyond annotations and clarifies the non-destructive but mutable nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the core purpose. Every sentence adds value: action, mechanism, and behavioral note. No redundant or missing parts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description covers the main behavior well but does not describe the return value or success/failure scenarios. It also does not mention prerequisites (e.g., endpoint must exist). Slightly incomplete for a mutation tool, but the core action is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all three parameters. The tool description does not add additional meaning beyond the schema. The mention of 'event ID is preserved' relates indirectly to the idempotency_key parameter but does not elaborate on parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retry a webhook delivery' with specific actions: resending the stored payload with a fresh signature and preserving event ID. It is distinct from siblings like tokportal_test_webhook_endpoint (which tests endpoint connectivity) and tokportal_list_webhook_deliveries (which lists past deliveries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it (e.g., after a failed delivery) or when to avoid it (e.g., if the endpoint URL has changed). No alternatives or exclusions are mentioned, though the context of sibling tools provides some implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint: false), not destructive (destructiveHint: false), and not idempotent (idempotentHint: false). The description adds useful behavioral context by listing the read-only states, but it does not explain the consequences of an update (e.g., whether changes immediately affect live behavior). It also does not clarify authentication requirements beyond 'API key owner'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences and front-loads the core purpose. The second and third sentences add necessary usage constraints. It earns points for being efficient, though one could argue the read-only status list could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (one being a complex nested object), no output schema, and moderate complexity, the description adequately covers inputs and preconditions but lacks information about the return value or confirmation of success. Since there is no output schema, the description should hint at what the response looks like (e.g., returns the updated profile), but it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema descriptions for parameters are already quite detailed (e.g., 'Saved account ID.', 'JSON request body.', 'Optional Idempotency-Key header for safe retries.'). The description does not add any additional parameter-level semantics, but given the high schema coverage, this is acceptable. The description compensates by explaining the overall purpose and constraints, which helps the agent understand what fields in the body are relevant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the specific resource 'account commenting profile'. It further details what fields are updated ('client-owned commenting/autopilot profile fields'), which distinguishes it from any sibling tool that might update different aspects of an account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool by specifying preconditions: the account must belong to the API key owner and have active TokPortal Coverage (unless permanently grandfathered). It also lists account states that are read-only ('Revealed/detached, banned, paused, lapsed and unrecoverable'), effectively telling the agent when NOT to use this tool. However, it doesn't explicitly name an alternative tool for those read-only states.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (write) and destructiveHint=false. The description adds context about the domain of settings affected and what is not exposed. However, it does not disclose side effects, mutability characteristics, idempotency behavior, or required permissions. Given sparse annotations, the description could provide more behavioral details (e.g., whether updates are partial, whether previous values are retained).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a tight three-sentence paragraph. Every sentence adds unique value: first states the action, second specifies the resource and context, third defines boundaries. No filler or redundancy. The information is front-loaded and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with no output schema and two parameters, the description covers the essential purpose and boundaries. It explains what fields are affected and explicitly rules out related settings. It could be slightly improved by stating that updates are partial (only provided fields are changed), which is implied by the schema but not stated. Nonetheless, the description is largely complete for an informed agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not repeat parameter details beyond what is in the schema. The schema itself documents maxLengths, nullability, and the idempotency_key purpose. The description adds no new semantics to parameters, so a baseline score of 3 is appropriate for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update safe workspace settings' and specifies the resource as 'client-owned workspace profile fields used by Operator context.' It also explicitly lists what it does not expose, distinguishing it from potentially similar tools like tokportal_update_account_commenting_profile. The verb and resource are specific and well-differentiated from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies appropriate usage by clarifying the scope (safe workspace settings for Operator context) and ruling out exposure of auth, role, credit, staff, or manager settings. However, it does not explicitly state when to use this tool versus alternatives or provide direct comparison to siblings. The 'does not expose' boundary helps, but explicit when-not guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits not captured by annotations: that it conditionally mutates (depending on Coverage), that a due active period can auto-renew at a stored rate, and that if Coverage cannot renew, no task or media mutation occurs. Annotations show destructiveHint: false, so this reveals that mutation is conditional and safe under some circumstances. However, it doesn't fully describe what happens to the bundle state, what triggers failure, or the exact return behavior (since no output schema exists). Still, it's a strong addition beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (3 sentences) and front-loads the main action ('Finalize video review') followed by conditional logic. Every sentence adds value: the first sets the purpose, the second details the Coverage rule, the third explains auto-renewal, and the fourth clarifies the no-op case. It could be slightly more terse by combining a few clauses, but it's efficient and readable with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, 3 parameters (all described in schema), and moderate complexity (conditional logic with Coverage), the description adequately covers the operational flow: finalization, Coverage requirement, auto-renewal, and no-operation fallback. The condition about 'no task or media mutation starts' is helpful. However, it doesn't explain what 'resolves to a delivered saved account' means in practice, nor does it clarify error states or how to interpret the outcome (since no output schema exists). This minor gap prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters (id, position, idempotency_key) are described in the schema. The description adds no specific information about these parameters beyond what the schema already provides (e.g., format, required status, optionality). The baseline of 3 is appropriate because the description doesn't enhance parameter understanding but doesn't contradict the schema either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Finalize video review' and explains the core conditional logic: if the bundle resolves to a delivered saved account, it must have active TokPortal Coverage or be permanently grandfathered. This is a specific verb+resource with a well-defined conditional action, distinguishing it from siblings like tokportal_publish_bundle (which focuses on publishing) and tokportal_finalize_bundle_account (which targets a different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: when finalizing a video review that involves account Coverage conditions. It explains the behavior around auto-renewal and no-operation if Coverage can't renew. However, it doesn't explicitly list alternatives or state when NOT to use it (e.g., if you haven't yet set up Coverage), nor does it mention prerequisites like ensuring Coverage terms are in place before calling. Still, the context is fairly clear for a specialized finalization tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds significant behavioral context beyond these: eventual consistency at period_end with a few-minute delay for the renewal worker, explicit period_expired boundary, the validity of zero-credit quotes, and the nuanced meaning of a 404 (grandfathered, ineligible, or not yet delivered). It also clarifies that coverage is independent from bundle completion, preventing false causal inferences. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core return values in the first sentence, then adds edge cases and behavioral notes in subsequent sentences. Every sentence adds unique value. At ~120 words, it is dense but not wasteful. A minor improvement could be to list return fields more structurally (e.g., bullet points) to improve scannability, but overall it is well-organized for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, so the description must fully document return semantics. It covers effective status, 30-day period, account rate, unpaid periods, task access, reactivation quote, period_end behavior, lock_version, and edge cases (grandfathering, 404 interpretation, zero-credit). However, it does not explicitly list every possible field (e.g., timestamps beyond current_period_end) and could benefit from a structured enumeration. Overall, sufficient for a complex domain but leaves minor ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (one 'id' param with description 'Saved account ID.'). The tool description does not elaborate on this parameter beyond the schema—it does not specify constraints (e.g., must be a saved account that was previously created), format expectations, or relationship to other entities. Given full schema coverage, the baseline is 3, and the description adds no extra semantic value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves TokPortal Coverage status and enumerates specific returned fields (status, period, rate, unpaid periods, task access, reactivation quote). This distinguishes it from sibling get tools like tokportal_get_account (which returns general account details) and tokportal_get_bundle_account (bundle-focused). The verb 'Get' and resource 'Coverage status' align precisely with the tool name's 'managed_subscription' domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to interpret results (grandfathered accounts, 404 meaning, zero-credit quote validity) but does not explicitly state when to use this tool versus alternatives like tokportal_reactivate_account_managed_subscription or tokportal_get_account. No context is given for prerequisites or conditions that should be checked before calling. The edge case guidance is helpful but usage direction is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and idempotent. The description adds value by stating that it returns blockers without mutating the bundle, settling Coverage, or debiting credits. It also explains the meaning of a specific error type and how to resolve it. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and then adds useful details about return behavior, error handling, and edge cases. Each sentence contributes meaningfully. It is slightly longer than necessary but still concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, read-only, no output schema), the description is quite complete. It explains what it returns, what it does not do, and how to handle a specific error. The only minor gap is the lack of a detailed return format, but the description is still informative enough for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter ('id') with a schema description of 'Bundle ID.' Schema coverage is 100%, so the description does not need to add extra parameter details. The description does not provide additional context about the parameter itself, but the schema is sufficient. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Check bundle publish readiness,' a clear verb+resource. It explains what it returns (publish blockers) and explicitly what it does not do (no mutation, no settling Coverage, no debiting credits), distinguishing it from sibling tools like 'tokportal_publish_bundle.' The mention of a specific error type and further guidance reinforces the precise purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (before publishing) and what to do if a specific blocker appears (fetch the managed subscription for authoritative state). It also warns about temporary blocks. While it does not explicitly name alternatives, the guidance is sufficient for correct use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the basic annotations (which only indicate non-readOnly, non-destructive, non-idempotent). It discloses that 7 credits are debited, the operation is atomic (assignment, debit, task creation), the routing logic for managers, eligibility rules for completed bundles, and the necessity to poll the GET endpoint. No contradictions with annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and covers many operational details, but it is somewhat verbose. For example, the paragraph on manager routing and eligibility could be shortened without losing clarity. While the core purpose is front-loaded, the extra details increase length beyond what is strictly necessary for a tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a nested input schema, 3 parameters, and no output schema, the description compensates well by explaining side effects (credit debit, atomicity), constraints (one request per video), and post-request actions (poll GET endpoint). It does not describe the return value, but that is acceptable since there is no output schema. Overall, it provides sufficient context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema for the parameters themselves. It mentions platforms (TikTok/Instagram) but the schema already describes them with an enum. The idempotency_key is not elaborated. Overall, the description adds no new semantic value for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's main action: 'Request an ad code (TikTok Spark Code / Instagram Partner Code) for a finalized video.' It names the specific resources (ad code, video) and the action (request). Among siblings, there is a separate GET endpoint for ad code requests, making this the sole creation tool, so sibling differentiation is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists prerequisites: video must be finalized with a live post link, active TokPortal Coverage, and a routable account manager. It also restricts to one open request per video. While it does not name alternative tools for non-finalized videos (e.g., bundling or finalization), the prerequisites serve as clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations are minimal (readOnlyHint=false, etc.), so the description carries the burden. It discloses that execution is blocking on coverage status, that the operation reverts a task to pending corrections, and references a specific error condition. This adds meaningful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the action and result; the second adds a critical precondition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, the effect, and a key blocking condition. It does not describe the return format or other potential errors, but given the lack of an output schema and the tool's focused scope, this is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters (id, body with nested reason, idempotency_key). The description does not add extra information about parameters beyond what the schema provides, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Dispute') and clearly identifies the resource ('manually confirmed comment task'), stating the precise outcome ('Returns an owned manually_confirmed task to pending corrections'). This distinguishes it from sibling tools like approve, delete, or get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when the tool is blocked (TokPortal Coverage inactive) and instructs to inspect MANAGED_ACCOUNT_TASK_BLOCKED and reactivate a recoverable account first. It implies usage for reversing a confirmation, though it does not explicitly compare to sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations (idempotentHint=true, readOnlyHint=false, destructiveHint=false) by detailing critical behavioral conditions: the account must have active TokPortal Coverage or be grandfathered, automatic renewal of due periods, and the consequence that 'If Coverage cannot renew, no task or media mutation starts.' It also clarifies that new accounts remain configurable before delivery. This provides rich context for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that front-loads the main purpose, then adds backward-compatibility guidance and behavioral conditions. While efficient, it is dense and could benefit from bullet points or clearer separation of concerns. Still, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, nested object, no output schema), the description covers the main purpose, usage alternatives, and important prerequisites like Coverage requirements. It lacks details on expected response format, error handling, or what happens if prerequisites are not met. However, it is sufficiently complete for an agent to understand when and how to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds a high-level summary of the identity fields and the advanced_warming_terms alternative, but does not add significant new meaning beyond the detailed schema descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's primary action: 'Configure bundle account profile. Sets the account identity (username, visible name, biography, profile picture).' It uses a specific verb ('configure') and resource ('bundle account profile'), and distinguishes itself from the sibling warming-terms endpoint by recommending the alternative for that purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when to use an alternative tool: 'For backward compatibility it can also accept the exact purchased advanced_warming_terms list, but PUT /bundles/{id}/warming-terms is the recommended one-shot deferred-target endpoint because it remains available at any account status.' This provides clear guidance on one specific sibling. However, it lacks broader guidance on when to use this tool versus other bundle account tools like finalize or request corrections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: the tool is blocked while TokPortal Coverage is inactive, with a specific error code and remediation step. It also clarifies the finalization behavior, which annotations don't convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the core purpose in the first sentence and a key prerequisite in the second. No redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, a critical blocking condition, and an error code. It doesn't mention the success response or return value, but with no output schema, this is a minor gap. Overall, it's sufficient for a simple approval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters already have meaningful descriptions in the schema. The description does not add extra parameter-level information, which is acceptable given the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Approve') and the resource ('comment task'), with specific scope ('owned manually_confirmed task') and finalization. This distinguishes it from sibling tools like delete, dispute, get, and list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: only for owned manually_confirmed tasks, and warns that execution is blocked when coverage is inactive. It doesn't explicitly name alternatives, but the state and ownership constraints effectively exclude other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotation 'destructiveHint=true' by detailing the immediate effect ('blocks new and ongoing work'), financial consequences ('Payments are not refunded'), and reactivation conditions (free vs. cost). This provides full behavioral transparency for a destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise four-sentence paragraph, front-loaded with the purpose 'Pause TokPortal Coverage.' Each sentence adds essential information (effect, payment, reactivation terms) without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, effects, and financial implications thoroughly. However, since there is no output schema, it would be slightly more complete if it mentioned what the tool returns (e.g., success status or updated subscription). Still, the behavioral context is strong enough for safe agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents both parameters ('id' and 'idempotency_key'). The description adds no parameter-specific information, so it meets the baseline of 3 without adding extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Pause TokPortal Coverage' and specifies 'Immediately blocks new and ongoing TokPortal work for the account.' This clearly states the verb (pause/block) and resource (TokPortal coverage/account managed subscription), distinguishing it from siblings like 'reactivate' and 'get'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to block coverage) and provides important context about payments, refunds, and reactivation costs. It implicitly references the reactivate tool and status endpoint, but does not explicitly name alternatives or state 'use this to cancel subscriptions.' This is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: sessions unlock over 3 calendar days in the manager's timezone, tasks do not expire, and the output includes per-term details and aggregated reports. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description enriches the agent's understanding of the data lifecycle.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and each sentence provides essential details without redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description covers the return content (tasks, reports, proof links, aggregated report) and temporal behavior (3-day unlock, non-expiry). It does not mention pagination or limits, but that may be acceptable for a listing tool that returns all sessions. Overall, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage (the 'id' parameter already has a description), the baseline is 3. The description adds value by specifying that the account must be a 'saved account you own', imposing a constraint beyond the schema's 'Saved account ID' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Advanced Niche Warming sessions for an account, specifies ordering (newest first), scope (saved account you own), and what is included (per-term tasks, reports, proof links, aggregated report). This distinguishes it from sibling tools like tokportal_get_warming_session, which retrieves a single session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (listing sessions for an owned account) but does not explicitly contrast with alternatives or state when not to use it. No guidance on when to prefer this over get_warming_session or other tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations, including that reactivation is free under certain conditions, atomic checks of credits/period/lock version, and that scheduled videos get new dates. No contradictions with annotations (readOnlyHint=false, etc.).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but efficient, with each sentence adding value. It is front-loaded with the main action and then explains conditions and edge cases. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (no output schema, nested parameters), the description covers all necessary aspects: the need for a GET snapshot, billing implications, atomic checks, and video scheduling behavior. It is sufficiently complete for an AI agent to operate correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all parameters. The description mentions expected_credits, expected_current_period_end, and expected_lock_version but does not add 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Reactivate TokPortal Coverage' and explains the action of reactivating from an explicit GET snapshot. It distinguishes itself from sibling tools like cancel_account_managed_subscription and get_account_managed_subscription by focusing on reactivation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool, such as the free reactivation during a paid billing period and handling of lapsed states at period end. It implies the need for a prior GET snapshot but does not explicitly list alternatives or when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behavioral traits beyond annotations: the irreversible nature, policy determination logic, credit costs, response error codes (428, 409), idempotency rejection, and long-term account effects (read-only, detach, end of support). Annotations only state non-readOnly, non-idempotent; the description fills in critical details. Score 4 because it is very comprehensive but could briefly mention the response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very dense and contains important details, but it is quite long and lacks clear section breaks (e.g., between policy explanation, error handling, and idempotency note). Every sentence earns its place, but structuring would improve scannability. Score 3 for being content-rich but structurally dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested required body, policy-based behavior, multiple error paths) and the absence of an output schema, the description is remarkably complete. It covers all key behavioral outcomes and error scenarios. Score 4 because a brief note on the expected success response content (e.g., verification code format) would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining the purpose of parameters in context of policy negotiation (e.g., policy_version used to detect stale quotes, acknowledge_support_forfeit acceptance). It also clarifies when body fields are required vs ignored. Score 4 because it enriches understanding well beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the latest account verification code and distinguishes it from the similar sibling `tokportal_reveal_account_credentials` by explaining it is equivalent to revealing credentials. The specific verb 'retrieve' and resource 'latest account verification code' are well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance by detailing the two policy scenarios (pre-cutoff vs post-cutoff) and the associated credit costs and behaviors. It also explicitly instructs not to send Idempotency-Key, explaining consequences. This clearly differentiates from siblings and advises on when not to call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides extensive behavioral details beyond the annotations (which are minimal: readOnlyHint=false, etc.). It explains the screen-recording process, verification, credit rate, pricing model (per target, never per day), legacy grace window closure date, term splitting over 3 days, and session non-expiration. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence adds substantive information. It is front-loaded with the primary purpose, then logically flows through process, costs, prerequisites, and time behaviors. Minor redundancy (e.g., rate repeated) but justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite comprehensive process and prerequisite details, the description omits what the tool returns (e.g., session ID, status). With no output schema, this is a gap. The agent is left to infer the outcome. Prerequisites and side effects are well-covered, but the return value is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with detailed descriptions for search_terms including rate and process. The description adds value beyond the schema by noting the legacy grace window closure (2026-08-14) and the GET /credit-costs endpoint for effective rates. This extra context improves parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Order Advanced Niche Warming (rewarm) on a delivered account,' using a specific verb ('order') and a clear resource ('Advanced Niche Warming on a delivered account'). It distinguishes this tool from sibling warming-related tools (e.g., configure_bundle_warming_terms, generate_warming_terms) by specifying it applies to delivered accounts and triggers an actual warming session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists prerequisites: active TokPortal Coverage, a routable active account manager backed by a non-cancelled support order, TikTok or Instagram platform, and no already-active warming session. It also states that a completed bundle remains eligible. While it does not name alternative tools for different scenarios, the conditions are clear enough to guide appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: explains that tasks remain open until completed and do not expire, and mentions the '3-calendar-day dispatch in the manager's timezone'. This provides transparency beyond annotations 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long with zero wasted words. It front-loads the core action ('Get an Advanced Niche Warming session') then efficiently lists return fields and a key behavioral detail about tasks. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully explains return values (status, per-term tasks with details, aggregated report). Given one parameter and rich annotations, this is a complete description for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'id' of type UUID and a schema description 'Warming session ID.' The description does not add further parameter meaning. Baseline of 3 is appropriate since the schema is already complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'an Advanced Niche Warming session'. It details what is returned (status, per-term tasks, aggregated report). It distinguishes this from sibling tools like 'tokportal_list_account_warming_sessions' by specifying it returns one session you own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to get a single session). It implies it is for retrieving owned sessions, which differentiates from listing tools. However, it does not explicitly state when not to use it or mention alternatives like 'tokportal_list_account_warming_sessions' for multiple sessions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, and title, leaving significant behavioral details undisclosed. The description compensates thoroughly: it reveals credit debit timing (immediately vs. at publish), the cutoff for new-customer benefits (immutable production instant from getCreditCosts), the idempotency model (external_ref vs. Idempotency-Key), and the auto-cancellation policy for unconfigured warming terms. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense but not concise. It packs 8+ distinct behavioral rules into a single block of 8 sentences, lacking visual structure (no bullet points or section breaks). The first sentence is immediate and clear, but the density may overwhelm an agent. A more structured approach (e.g., subsections for 'Payment', 'Warming Terms', 'Idempotency') would improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high complexity (2 params, nested object with 16 sub-fields, no output schema, and 66 siblings), the description covers the most critical behavioral aspects: atomicity, credit timing, warming term configuration, and idempotency. It lacks guidance on response format (what fields to expect on success/error), and the schema already handles parameter validation. A small gap exists in not describing the 'edits_quantity' or 'videos_quantity' semantics, though those are somewhat self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds significant value beyond the schema: it explains the relationship between advanced_warming_terms and advanced_warming_terms_count (pass one or the other), the auto-cancellation behavior for count-only purchases, and the distinction between external_ref and Idempotency-Key. However, the description doesn't explicitly connect each schema parameter to the broader workflow—some details (like the country requirement exception for videos_only) are left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create a bundle'), the resource ('bundle'), and specifies three bundle types (account-only, account-and-videos, videos-only) with the critical detail of atomic creation checkout. It distinguishes this from sibling tools by emphasizing the atomic payment and creation aspect, which no other sibling tool (like tokportal_create_bundles_bulk or tokportal_update_bundle) covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive when-to-use guidance: it explains prerequisites (getCreditCosts for credit cost), the credit debit timing (immediately on POST, not at publish), and implicit alternatives (e.g., configuring warming terms later via PUT /bundles/{id}/warming-terms). It also defines conditions for auto-cancellation and refunds (14 days for unconfigured count-only purchases), helping the agent decide when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-readOnly, non-idempotent, and non-destructive, but the description goes far beyond by detailing atomic rollback on failure, immediate credit debit (not at publication), consumption of contract_bundle_allowance slots in deterministic order, and partial price for batches crossing the final slot. It also explains the advanced warming options' behavior (later configuration, auto-cancel after 14 days). 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is comprehensive but moderately long. It front-loads the core purpose in the first sentence but includes dense technical details (allowance slots, contract prices, advanced warming nuances) that could be more structured. Every sentence earns its place, but the length relative to context signals (2 params, no output schema) suggests minor trimming or bullet-pointing would improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested body object, multiple warming options, rollback semantics, credit costing) and no output schema, the description covers key aspects: return values implied by external_ref and bundle IDs, credit mechanics, rollback behavior, and warming configuration paths. It's complete for a bulk creation tool, though missing explicit mention of potential error states beyond rollback.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions on parameters like external_ref, wants_deep_warming, advanced_warming_terms, and advanced_warming_terms_count. The description adds value by explaining the batch-level semantics of external_ref (not a retry mechanism) and the interplay between the two advanced warming alternatives, but the schema already covers most nuances well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Create', 'pays') and a clear resource ('bundles in bulk'), and explicitly states an atomic creation checkout with immediate credit debit. This distinguishes it from its close sibling tokportal_create_bundle (single) and other tools (e.g., tokportal_configure_bundle_warming_terms) by clarifying the batch nature and payment mechanics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed when-to-use guidance (for bulk creation with atomic checkout), when-not-to-use (for single bundles use create_bundle, for configuration after purchase use warming-terms endpoints), and explicit alternatives (advanced_warming_terms vs advanced_warming_terms_count). It also explains gotchas like external_ref not being an idempotency key and the rollback behavior on failure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations that indicate mutation and non-idempotency, the description discloses partial-success semantics, per-task credit debit, no charge for rejected rows, account lock/revalidation, single-transaction commit, and idempotency replay behavior. This is rich behavioral detail that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then efficiently covers prerequisites, billing, transactionality, and idempotency in dense but purposeful sentences. Every sentence adds necessary operational information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex batch mutation tool with no output schema, the description covers prerequisites, batch size, credit costs, partial success, idempotency, and a response field hint ('credits_charged'). It could more explicitly describe the response shape or partial-success structure, but it is largely complete for operational use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful operational semantics beyond the schema: credit cost per accepted task, requirement for Idempotency-Key, and the directive to read 'credits_charged' rather than calculating it. This supplements the parameter-level documentation effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create comment tasks' and clearly states the scope: 'Creates one comment task or a partial-success batch of up to 200.' This provides a specific verb, resource, and batch capability, distinguishing it from sibling tools like list_comment_tasks, get_comment_task, and delete_comment_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context: prerequisites for the saved account, TokPortal Coverage requirements, credit costing, transactional behavior, and explicit Idempotency-Key guidance. It does not explicitly name alternative tools or when-not-to-use scenarios, but the operational context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the operation is free and does not charge credits, which adds useful behavioral context beyond the annotations (which only indicate non-read-only, non-destructive, non-idempotent, non-open-world). It does not discuss any potential side effects or limitations (such as rate limits), but the transparency is good overall.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (four short sentences), front-loads the key purpose, and every sentence adds essential guidance. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and moderate complexity with three nested parameters, the description adequately covers the purpose, workflow, and usage. It's complete enough for an agent to use correctly, though additional details about output structure would be ideal but not strictly necessary given the downstream integration guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters well. The description adds value by clarifying that the 'text' parameter should be a 'free-text niche description' and that language is inferred, and hints at the count constraint (multiple of 3). This goes slightly beyond the basic schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'generate' and the resource 'Advanced Niche Warming search terms', and specifies it takes a free-text niche description up to 1000 characters. It also distinguishes itself from sibling tools like tokportal_configure_bundle_warming_terms by noting the output is passed to advanced_warming_terms or search_terms for subsequent use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (to generate search terms from a niche description) and provides clear guidance on what to do with the result ('Pass the result to advanced_warming_terms... or search_terms'). This effectively differentiates it from related tools and outlines the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only, idempotent, and non-destructive. The description adds the 'public' behavior detail (no auth needed?), which is helpful beyond annotations. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each adding value: first states the action and returns, second provides behavioral context (public), third states audience. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no complex schema, and strong annotations, the description fully explains purpose, usage context, and behavior. No output schema exists, but return values are summarized adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema is fully descriptive. The description adds no parameter info, but there is nothing to add. This is a perfect baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists webhook event types, and specifies what is returned: types, delivery envelope, signature scheme, and example payloads. It is distinct from sibling tools focused on managing endpoints or deliveries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes this is a public endpoint for inspecting contracts before creating an API key, implying it should be used for pre-configuration exploration. No alternative or when-not-to-use guidance is given, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true, but the description adds significant behavioral context: it explains the atomic commit of terminal transition and refund, notes that credits_refunded is authoritative for historical tasks, clarifies the refund amount for current tasks (1 credit), and explains why cancellation works during paused Coverage. This goes well beyond the annotations, providing a thorough behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 5 sentences, with front-loaded purpose and key conditions. Each sentence adds essential information: scope, state constraint, atomic behavior, historical nuance, coverage exception, and idempotency guidance. There is no fluff, but it could be slightly more streamlined by merging the coverage and retry points into a single sentence without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (credit mutation, idempotency, state-dependent behavior) and the absence of an output schema, the description covers the critical behavioral aspects: what happens atomically, refund semantics, and retry safety. However, it omits details about the return value (e.g., confirmation of cancellation or updated task status), which would improve completeness for an agent that needs to verify success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the idempotency key reuse guidance and the context of credit refund, which is not detailed in the schema. However, it does not elaborate on the 'id' parameter beyond what the schema provides (UUID format), missing an opportunity to reinforce the ownership constraint. Still, it adds meaningful context above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Cancel a pending comment task') and specifies the resource ('comment task'). It distinguishes this from sibling tools like tokportal_approve_comment_task and tokportal_dispute_comment_task by focusing on cancellation, and further clarifies scope by noting it only cancels an 'owned task' in 'pending' status, leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Cancel a pending comment task' with the constraint 'only while its status is pending.' It also states when not to use it by implication (only owned tasks) and mentions an important context where it remains available ('when Coverage is paused'). Additionally, it advises on retry behavior with the Idempotency-Key, helping the agent decide to reuse it after uncertain transport results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds rich behavioral details: pollable list, lifecycle status meanings, resolution codes, screenshot URL behavior, and the exclusion of internal health scans. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-organized paragraph. It front-loads the core purpose, then efficiently covers scope, lifecycle, polling behavior, and exclusions. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, multiple enums, polling, lifecycle states), the description covers all essential aspects: what is listed, what is excluded, how to poll, meaning of statuses and resolutions, and screenshot feature. No output schema is present, but the description sufficiently describes what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a description. The description adds context beyond the schema, such as explaining that 'since' is a polling watermark, what each status enum value means (e.g., 'appeal_pending' means account unavailable but not yet banned), and that 'include_screenshots' provides signed 7-day URLs. This adds significant domain understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists ban reports and appeals, covering the full lifecycle with specific statuses. It distinguishes from internal health scans and webhook events, making its unique purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit polling guidance with the 'since' parameter and explains what data is included. Tells users that only staff/CM-validated bans appear, ruling out internal health scan detections. Does not name specific sibling alternatives, but no other sibling serves the same purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations' basic flags. It discloses irreversibility, account detachment, read-only transition, end of coverage, atomic commits, idempotency restrictions (rejection with specific error), and refund policy. It fully describes what gets destroyed/mutated despite no destructiveHint annotation, adding immense value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely packed with necessary detail. It front-loads the core action and pricing rule in the first sentence. While it could be slightly trimmed (e.g., the closing instruction on uncertain transport could be shorter), every sentence provides unique value for a high-stakes credential reveal operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's sensitivity, complexity (pricing rules, cutover logic, atomic operations), and lack of output schema, the description is remarkably complete. It covers pre/post conditions, error scenarios (428, 409), idempotency handling, and post-operation state. The sibling tool list confirms no other tool duplicates this functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers parameters fully (100% description coverage), so baseline is 3. However, the description adds critical context for both parameters: it explains the policy_version source (from error responses) and the acknowledge_support_forfeit meaning (confirmation of specific disclosure). This justifies a higher score as it clarifies complex required behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Reveal delivered account credentials', a specific verb+resource pair that exactly matches the tool name. It clearly distinguishes this tool from siblings like tokportal_retrieve_account_verification_code and tokportal_get_account by focusing on credential reveal and its unique pricing/behavioral rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive when-to-use and when-not-to-use guidance. It explicitly separates pre-cutoff vs post-cutoff accounts, explains pricing conditions, details the idempotency header prohibition, and advises on handling uncertain transport results. This is exceptionally detailed for usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![langchain-tokportal MCP server](https://glama.ai/mcp/servers/tokportal/langchain-tokportal/badges/card.svg)](https://glama.ai/mcp/servers/tokportal/langchain-tokportal)

Score Badge

Copy to your README.md:

[![langchain-tokportal MCP server](https://glama.ai/mcp/servers/tokportal/langchain-tokportal/badges/score.svg)](https://glama.ai/mcp/servers/tokportal/langchain-tokportal)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tokportal/langchain-tokportal'

If you have feedback or need assistance with the MCP directory API, please join our Discord server