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
Disambiguation3/5
Many tools exist (91), and while descriptions are detailed, overlapping categories like analytics (16 tools) and multiple account-related operations can confuse an agent. Tools such as tokportal_get_analytics_series, tokportal_get_analytics_account, and tokportal_get_account_analytics have similar purposes despite different scopes, increasing misselection risk.
Naming Consistency5/5
All tools follow the tokportal_verb_noun pattern with snake_case. Verbs like list, get, create, update, delete, publish, configure are used consistently. Minor deviations like tokportal_can_refresh_account_analytics and tokportal_fix_bundle_video_download are still clear and fit the pattern. Excellent consistency.
Tool Count1/5
91 tools is extremely high for a single MCP server. This scoping seems excessive; the functionality could be split into multiple focused servers (e.g., analytics, bundles, accounts, webhooks). The count far exceeds typical well-scoped servers (3-15 tools) and hinders agent efficiency.
Completeness4/5
The tool set covers the full lifecycle of TokPortal operations: account management, bundles, video slots, analytics, comment tasks, webhooks, uploads, and subscriptions. There are no obvious major gaps. Minor missing features (e.g., deleting analytics reports) might exist but core workflows are well-covered.
Average 3.6/5 across 91 of 91 tools scored. Lowest: 2.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits 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

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what annotations already declare (readOnlyHint=true, destructiveHint=false). It does not mention performance, error behavior, authentication needs, or any side effects. With annotations present, the description's silence on behavior is a missed opportunity and leaves the agent without 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (four words), but brevity here comes at the cost of informativeness. It front-loads the verb but omits critical detail, making it under-specified rather than efficiently concise. Every sentence should earn its place; this single sentence adds little value.
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 the tool's many siblings (over 70 tools including several analytics endpoints), the lack of output schema, and the opaque term 'compatibility view,' the description is severely incomplete. It fails to explain what the tool returns, how to interpret the result, or how it differs from closely related tools like 'tokportal_get_analytics_dashboard.' The description is insufficient for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single parameter 'id' with a description ('Saved account ID.'), achieving 100% schema coverage. The tool description does not mention parameters, so it adds no meaning beyond the schema. Per the rubric, when schema coverage is high, the baseline score is 3, and the description neither improves nor worsens the semantic understanding.
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 'Get account analytics compatibility view,' which provides a verb and resource, distinguishing it from siblings like 'tokportal_get_analytics_account' by its focus on 'compatibility view.' However, the term 'compatibility view' is vague and not defined, leaving the exact purpose unclear. It is not a tautology but lacks sufficient specificity for a clear 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 offers no guidance on when to use this tool versus its many siblings, such as 'tokportal_get_analytics_series' or 'tokportal_get_analytics_account.' There is no mention of context, prerequisites, or exclusions. The agent receives no help in deciding between this and alternative analytics 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which already communicate that this is a safe, read-only, idempotent operation. The description adds no further behavioral details, but it does not contradict the annotations. The annotations carry the transparency burden, so a score of 3 is appropriate for not providing additional context beyond the structured data.
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 (three words), which could be concise if it were informative, but here it is under-specified. The required information for an analytics dashboard tool is missing, making it insufficient rather than efficiently brief.
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 (including filters for account, country, platform, workspace, and a date range), no output schema, and a complex ecosystem of sibling tools, the description is highly incomplete. It does not explain what the dashboard returns, how filters combine, or what aggregation or time period is implied. Significant gaps remain.
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 thoroughly documents all 6 parameters. The description does not add any additional meaning or context for the parameters. Per the rules, this justifies a baseline of 3.
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 analytics dashboard' identifies a specific resource (analytics dashboard) but does not clarify what this dashboard contains or how it differs from sibling analytics tools like 'tokportal_get_analytics_series' or 'tokportal_get_analytics_account'. The verb 'Get' is generic, and without context on the dashboard's scope (e.g., aggregated metrics, charts), the purpose is vague and poorly differentiated.
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 the many alternative analytics or dashboard-related siblings. There is no mention of prerequisites, context, or scenarios where this tool is preferred. The description offers zero usage direction.
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 it is a safe, non-destructive operation. The description does not add any behavioral context beyond these hints. It does not contradict annotations, so the score is moderate.
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 at four words. While brevity can be good, here it sacrifices clarity. A slightly more informative sentence would not harm conciseness and would better serve the purpose.
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 and the simplicity of a single parameter, the description is still too minimal. It does not explain what the returned bundle contains or how to interpret the response, leaving the agent without essential execution 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% for the single parameter 'id' (a UUID). The description 'Bundle ID.' in the schema already explains its meaning. The tool description adds no further context about what identifier formats or bundle types are acceptable, so it does not exceed the baseline.
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.' is a minimal tautology of the tool name 'tokportal_get_bundle'. It does not specify what a bundle is, its scope, or how it differs from sibling tools like 'tokportal_get_bundle_video', 'tokportal_get_bundle_account', or 'tokportal_get_bundle_publish_readiness'.
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?
The description provides no guidance on when to use this tool versus alternatives. With many sibling tools like 'tokportal_list_bundles', 'tokportal_get_bundle_publish_readiness', or 'tokportal_get_bundle_video', there is no context to help an agent choose correctly.
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 declare destructiveHint: false and idempotentHint: false, so the description should clarify behavior such as whether this is an additive operation (non-destructive) and that retries are not safe without an idempotency key. The description simply restates the tool's function without addressing these traits, creating ambiguity about whether adding slots updates an existing bundle or creates separate resource records.
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 concise at one sentence. It is front-loaded with the core action. However, it is so brief that it sacrifices necessary detail for an agent to use the tool correctly, so it cannot score 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 the nested body object and the lack of an output schema, the description should explain what the tool returns (e.g., updated bundle object, list of added slots) and any side effects (e.g., triggers pricing or availability checks). It provides none of this context, leaving critical gaps for an AI 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 description coverage is 100%, with all three parameters documented in the schema. The description adds no new meaning beyond what the schema already provides (e.g., id is a bundle UUID, body contains a quantity). Baseline 3 is appropriate since the description does not enhance parameter understanding.
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 "Add video slots to a bundle" conveys a clear verb and resource, but it fails to meaningfully distinguish this tool from tokportal_add_edit_slots, which likely serves a similar purpose for a different slot type. The sibling list includes both tools, yet the description provides no unique qualifier such as "sponsored" or "promotional" slots, leaving an agent to guess the difference.
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 explicit guidance is provided on when to use this tool versus siblings like tokportal_add_edit_slots or tokportal_publish_bundle. The context of bundles and slots is implied by the name, but there is no mention of prerequisites (e.g., bundle must exist) or constraints (e.g., maximum slots per bundle).
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 correctly indicate readOnlyHint=true and destructiveHint=false, so the description doesn't contradict them. While it adds no behavioral detail beyond the annotations—e.g., it doesn't mention that listing might have performance implications or require any authentication—the annotations already cover the safety profile, so 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 two words—clear and brief, but it's under-specified rather than concisely informative. It doesn't earn its place by adding value beyond the tool name. A moderate score reflects that it is not bloated, but also not helpful.
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 with no output schema and no description of the return structure, the description is insufficient. The agent cannot infer what data is returned (e.g., paginated list with total count, metadata) or how to leverage the available filters. This is a significant gap for a data-listing tool.
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 schema already documents all 7 parameters well, including enums for platform and bundle_type. The description adds no parameter-specific guidance, but given full schema coverage, the baseline is 3, and the concise description (though minimal) does not detract, earning a 4.
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 is 'List bundles.' which is a tautology—it simply restates the tool's name without adding specifics about what operations are available (e.g., filtering, pagination) or how this differs from 80+ siblings, some of which also involve bundles.
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 usage context is provided. Among numerous bundle-related siblings like tokportal_list_account_bundles and tokportal_list_bundle_videos, the description offers no guidance on when to use this tool versus alternatives (e.g., listing all bundles vs. bundles for a specific account vs. videos within a bundle).
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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which already convey safety. The description adds no behavioral context beyond the title—e.g., it doesn't explain what 'availability' means (returns a boolean? error if not available?), what gets checked (e.g., rate limits, data freshness), or the response format. With strong annotations, the bar is lower, but the description still fails to add meaningful transparency.
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 plus article), which is concise but lacks substance. Every sentence should earn its place, but here it barely provides information, resulting in under-specification rather than efficient clarity.
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 large sibling list (especially the closely related 'tokportal_refresh_analytics_account'), the description should clarify the tool's role as a non-mutating query for availability. Without output schema or additional context, an agent cannot distinguish this from other analytics reads or know what action to take based on the result, leaving the description 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 description coverage is 100% and there is only 1 parameter ('id' as a uuid with description 'Saved account ID.'). The description does not add further semantics about this parameter (e.g., 'The ID of the account to check for refresh availability'), but since the schema already fully documents it, a baseline 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 'Check analytics refresh availability,' which gives a clear verb ('check') and resource ('analytics refresh availability'). However, it does not distinguish this tool from its sibling 'tokportal_refresh_analytics_account' (which presumably triggers a refresh) or other analytics-adjacent tools, lacking specificity about what 'availability' entails (e.g., whether a refresh is currently allowed or whether data is ready).
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_refresh_analytics_account' or 'tokportal_get_account_analytics.' It does not state that this is a precondition check (e.g., 'call this before refresh_analytics_account'), nor does it mention any context like prerequisites (e.g., account must exist).
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 readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context. It does not clarify whether the update is partial or full replacement, what happens to unspecified fields, or any side effects. The name implies mutation, but beyond that, the agent gains no insight into the tool's behavior.
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 concise at four words. It is efficient and front-loaded. However, for a tool with nested parameters and multiple siblings, the brevity may come at the cost of completeness, but it does not contain unnecessary content.
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 (3 parameters, nested body object, no output schema, many siblings), the description is severely lacking. It does not explain return values, error handling, partial update behavior, or any constraints. The agent is left with minimal 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% (all parameters have descriptions in the schema). The tool description adds no additional meaning to the parameters; it merely restates the tool's purpose. With high schema coverage, the baseline is 3, and the description does not improve upon it.
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 'Update a webhook endpoint' clearly states the verb and resource, but it is very generic. It does not differentiate this tool from siblings like 'create_webhook_endpoint' or 'delete_webhook_endpoint', which are also present in the sibling list. The name itself is explanatory, but the description adds no additional specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description lacks any mention of prerequisites, context (e.g., updating an existing endpoint vs creating a new one), or when not to use it. Given the many sibling tools, this omission hinders correct tool selection.
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 only provide default false hints (readOnly, destructive, etc.), offering no behavioral insight. The description adds no information about side effects, required permissions, error conditions, or retry behavior beyond the idempotency_key parameter (which is in the schema but not in the description). For a mutation tool, this is insufficient.
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 sentence that is concise but arguably too brief. It conveys the core action without waste, but could incorporate more context (e.g., slot quantity range, idempotency support) without becoming verbose. Front-loading is acceptable but would benefit from immediate distinction from sibling tools.
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 (nested body parameter with constraints) and the existence of a closely related sibling ('add_video_slots'), the description lacks crucial context. It does not explain what 'edit slots' are, how they relate to video slots, what happens after adding (e.g., response, impact on bundle state), or any error conditions. The absence of an output schema further increases the need for descriptive 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%: each parameter has a brief description (e.g., 'Bundle ID', 'JSON request body'). While the tool description does not add further meaning, the schema already adequately documents the parameters. Baseline 3 is appropriate as the description does not degrade understanding.
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 ('Add edit slots') and the resource ('a bundle'), making the primary function understandable. However, it does not distinguish this tool from the sibling 'tokportal_add_video_slots', which likely performs a similar operation for video slots, limiting differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'add_video_slots' or other bundle modification tools. It lacks any mention of prerequisites (e.g., must have a bundle created already), context, 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 and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that the output is a CSV file, which is useful beyond annotations. However, it does not disclose any rate-limiting, pagination, or data volume characteristics—though with no destructive behavior, the transparency is adequate. 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 short sentence with no wasted words. It is front-loaded with the verb and resource, making it efficient. Slight improvement could be made by adding a brief usage note without increasing length significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and no output schema, the description is too sparse. It does not explain return format beyond 'CSV', nor the behavior of the date range, repeatable filters, or workspace. Given the schema coverage and lack of output schema, more context is needed for correct 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 description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema provides (e.g., no explanation of how filters combine or what 'Repeatable' means in practice). For 7 parameters, the description is minimal.
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 'Export analytics videos CSV' states the verb 'Export', resource 'analytics videos', and output format 'CSV'. However, among sibling tools like 'tokportal_export_analytics_report_html' and numerous analytics-related tools, it does not differentiate its scope (e.g., what specific video analytics are exported, or how it differs from other export/get 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 is provided on when to use this tool vs. alternatives such as 'tokportal_get_video_analytics', 'tokportal_list_account_video_analytics', or 'tokportal_export_analytics_report_html'. There is no mention of prerequisites, context, or exclusions, leaving the agent to guess usage intent.
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 of safe read-only behavior. The description adds nothing beyond the operation name, but does not contradict annotations. Given the annotation coverage, a score of 3 is appropriate as the description provides minimal 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 sentence of 4 words, highly concise and front-loaded. However, it is so terse that some useful context (e.g., 'by ID') is omitted. It earns its place but 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?
With no output schema, the agent has no information about what the response contains. The description does not mention that the tool returns a webhook endpoint object or any prerequisites (e.g., the endpoint must exist). Given the low complexity (1 param, annotations present), the description is incomplete for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter (id) with 100% schema description coverage: 'Webhook endpoint ID.' The description 'Get a webhook endpoint' implicitly requires an ID, but adds no extra 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.
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 resource 'webhook endpoint', but it does not distinguish from the sibling 'tokportal_list_webhook_endpoints' which retrieves multiple endpoints. The purpose is clear but lacks explicit differentiation, making it adequate but not outstanding.
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 such as list_webhook_endpoints (to retrieve all endpoints) or create/update/delete. The agent receives no context for selecting this tool over its 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds the 'delivered account' constraint, but doesn't disclose any other behavioral traits like pagination defaults or potential errors. Score is adequate given annotations already provide key transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, making it very concise. It is front-loaded with the action, but could benefit from structural elements like a note on algorithm or alternative. Still, it earns its place without redundancy.
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 4 parameters (including pagination and filtering), no output schema, and a large sibling set, the description is too sparse. It doesn't explain return value format, how filtering by status works, or how the tool relates to others like tokportal_list_bundles. Completeness is lacking for contextual richness.
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 four parameters (id, page, status, per_page) with their types and constraints. The description adds no additional meaning beyond what's in the schema, so baseline 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 'List bundles for a delivered account', which specifies a verb and resource. However, it doesn't clarify what a 'delivered account' means, leaving ambiguity about the tool's scope. The sibling tool 'tokportal_list_bundles' likely lists bundles more broadly, but the description doesn't differentiate between them, so purpose is somewhat 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?
No guidance is provided on when to use this tool versus tokportal_list_bundles or other bundle-related tools. The description gives no context for when a delivered account applies or excludes alternatives, leaving the agent to infer usage without support.
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 destructiveHint=true, so the mutation is expected. The description adds useful behavioral context: the operation may not execute if coverage cannot renew, and it mentions automatic renewal behavior. However, it fails to disclose what happens on success (e.g., the new state of the slot) and what the return value is. With no output schema, the description carries a heavier burden that it only partially meets.
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: the first states the purpose, the second adds conditions. It is reasonably brief and avoids unnecessary detail, though the second sentence is dense with multiple clauses. It is front-loaded and efficient for a destructive tool with complex prerequisites.
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 having good schema coverage and some behavioral notes, the description lacks essential context. There is no explanation of what 'reset' accomplishes, no return value or confirmation behavior, no mention of ordering relative to other bundle operations (e.g., does it need to follow configure or precede publish?), and no link to related tools. For a destructive operation with no output schema, this 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?
Schema description coverage is 100%, so each parameter (id, position, idempotency_key) already has a clear definition in the schema. The tool description adds no extra meaning or usage hints beyond what is already structured. Baseline of 3 is appropriate since the schema does the heavy lifting.
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 starts with 'Reset one video slot,' which is a clear verb-resource pair, but it never defines what 'reset' actually does to the video slot. It focuses on coverage and renewal conditions rather than the core operation, leaving ambiguity about whether it removes, reinitializes, or repositions the video. Compared to siblings like configure_bundle_video or publish_bundle_video, the exact scope of 'reset' is not differentiated.
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 zero guidance on when to use this tool instead of alternatives like unschedule_bundle_video, finalize_bundle_video, or configure_bundle_video. It does not mention prerequisites beyond coverage conditions, nor does it offer when-not use cases. The agent is left to infer context 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide limited info (readOnlyHint=false, destructiveHint=false). Description adds only that it creates a 'standalone downloadable' report, but does not disclose how the output is delivered (download URL? direct file?), auth requirements, rate limits, or side effects like consuming credits. With no output schema, the description fails to fully explain the behavioral outcome.
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?
Two short sentences with no wasted words. Front-loaded with the action. Could include more detail (like output delivery method) without harming conciseness, but overall it is 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?
Despite the complexity (11 nested parameters, no output schema), the description is extremely minimal. Does not explain return behavior, authentication needs, or how the parameters affect the exported report. For a tool that likely produces a file, this is a significant completeness gap.
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% only for the 2 top-level parameters (body and idempotency_key), but body's nested properties (11 fields like to, from, query, template, etc.) have no descriptions in schema or tool description. The tool description adds no meaning to parameters, leaving an agent to guess how to populate the body correctly.
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?
Clearly states the verb (export), resource (analytics report), format (HTML), and result (standalone downloadable). Distinguishes from siblings like tokportal_export_analytics_videos which exports videos, not a report. The purpose is specific and 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?
No usage guidelines provided. Does not explain when to use this tool versus alternatives like tokportal_create_analytics_report (creates a report, not exporting) or tokportal_get_analytics_dashboard (retrieves a dashboard). No prerequisites or when-not-to-use guidance.
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, destructiveHint=false, and openWorldHint=false, which is strong. The description adds the phrase 'drilldown' which implies a more detailed or expanded view beyond a simple aggregate, but doesn't add specific behavioral traits such as pagination, data freshness, or limitations 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no wasted words. It is concise, though the word 'drilldown' could be more specific to avoid ambiguity.
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 tool with one parameter, full annotations, no output schema, and low complexity, the description is adequate but not complete. It doesn't explain what 'drilldown' produces (e.g., a breakdown by date/region/video) or what the output format is, which an agent might need to decide between this and tokportal_get_account_analytics.
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 exactly one parameter 'id' (UUID, 'Saved account ID.'). The description adds no further meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'get' account analytics 'drilldown', but 'drilldown' is vague and doesn't specify what dataset/metric is being drilled into. Among siblings, there are multiple analytics tools (e.g., tokportal_get_account_analytics, tokportal_get_analytics_series), but the description does not differentiate what drilldown means versus those.
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 versus alternatives like tokportal_get_account_analytics or tokportal_list_analytics_account_raw_snapshots. The description does not suggest prerequisites, typical use cases, or when to avoid 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, destructiveHint=false, and openWorldHint=false. The description adds no behavioral detail beyond these hints. Since the annotations cover the safety profile well, a 3 is appropriate; the description itself does not enrich behavioral expectations (e.g., whether data is real-time, cached, or rate-limited).
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 fits the tool name. No wasted words. However, it could be slightly more descriptive without losing conciseness (e.g., specifying temporal aggregation or return granularity).
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 8 optional parameters with 100% schema coverage but generic descriptions, and no output schema, the description is minimally viable. It does not explain the return type (e.g., timestamped series, aggregated metrics) or required context (e.g., which parameters are filters vs. required for meaningful results). The lack of output schema increases burden on the description, which it does not address.
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%, but descriptions are generic ('query parameter <name>'). The description provides no additional meaning—e.g., it does not explain what 'pulse' means, how 'to'/'from' relate to time range semantics, nor how 'post', 'account', 'platform', 'country' filter results. With full schema coverage, baseline is 3, and the description adds 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 comment pulse analytics' matches the tool name and sibling prefix. It clearly indicates the tool retrieves analytics data related to comments. However, it does not specify the scope (e.g., per account, per post, or aggregated) nor differentiate from analytics siblings like tokportal_get_analytics_series or tokportal_get_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?
No guidance on when to use this tool versus alternatives (e.g., for series trends, use tokportal_get_analytics_series). There is no statement of excluded conditions or required context (e.g., whether a post or account must be specified). The description offers no usage context for the AI agent.
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 behavior as a safe, idempotent read is clear. The description adds no additional behavioral context (e.g., response structure, data freshness, rate limits). With annotations covering safety, 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 short sentence, which is concise but lacks any structural detail. It earns its place but does not provide additional useful information beyond the tool name.
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 low complexity (one param, no output schema), the description omits what the tool returns (e.g., metrics, format). Without an output schema, the agent needs more context about the response. The description is too brief to be considered 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?
The schema provides 100% coverage with a single parameter 'id' described as 'Video ID.' The description does not add any further semantics beyond the schema. Given full schema coverage, the baseline is 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 'Get single video analytics' clearly states the verb ('Get') and resource ('video analytics'), and the adjective 'single' differentiates it from list-oriented siblings like tokportal_list_account_video_analytics. However, the description does not elaborate on what specific analytics data is returned, leaving some 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?
The description provides no explicit guidance on when to use this tool versus siblings such as tokportal_get_analytics_series or tokportal_get_account_analytics. It does not mention use cases, prerequisites, or alternatives, relying solely on the tool name for 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 context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It does not explain what 'delivered' means, how pagination works, or what the response looks like. For a list tool with no output schema, some behavioral disclosure would be valuable.
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 with no wasted words. It is concise and front-loaded. However, it is almost too brief and could benefit from a bit more structure or context without losing 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?
Given the tool has 5 parameters, no output schema, and no behavioral annotations, the description should provide more context about what 'delivered accounts' means, the expected response format, and any constraints. The current description is incomplete for an agent to fully understand the tool's behavior.
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 each parameter has a description (e.g., page, banned, country, per_page, platform). The description adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate as the schema carries the burden adequately.
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 delivered accounts.' clearly states the action (list) and the resource (delivered accounts). It is specific enough to convey the core function, but it does not differentiate this tool from siblings like tokportal_get_account or tokportal_list_account_bans, which could cause confusion about which tool 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 provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context for when 'delivered accounts' is the appropriate scope. With many sibling tools, this omission makes it harder for an agent to select the correct tool.
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, so the safety profile is covered. However, the description adds only the word 'active', which hints at filtering behavior but does not explain what happens if no active request exists, whether the request is mutable, or any other behavioral detail 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it is under-specified—it lacks necessary context that would make the sentence more valuable. It earns its place as a purpose statement, but does not cover other essential aspects.
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 is simple (one required parameter, no output schema, annotations present), but the description fails to explain what an 'account edit request' is, what 'active' means, or what the return value contains. Without an output schema, the agent has no insight into the structure or content of the response.
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 lone parameter 'id' is described as 'Saved account ID.'). The tool description does not add any additional meaning about this parameter, but the baseline score of 3 is appropriate since the schema already documents the parameter adequately.
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 active account edit request' uses a specific verb ('Get') and clearly identifies the resource ('active account edit request'), distinguishing it from sibling tools like tokportal_create_account_edit_request that perform different operations.
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_get_account, tokportal_get_bundle). There is no mention of prerequisites, what constitutes an 'active' request, or when another tool 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.
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 does not add any behavioral context beyond annotations, such as rate limits, authentication needs, or data volume implications. It neither contradicts nor enriches the annotations, scoring baseline adequacy.
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, which is highly concise and front-loaded. Every word earns its place, but the extreme brevity sacrifices helpful detail. It is not verbose, but arguably too minimal for a tool with six parameters and multiple siblings.
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 (3 with enums), no output schema, and numerous sibling analytics tools, the description is severely incomplete. It does not explain what the time series contains (e.g., data points with timestamps and metric values), how parameters combine, or how the output is structured. Relies entirely on schema and annotations, which are themselves thin.
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. However, the schema descriptions are minimal (e.g., 'query parameter to' for the date parameter) and the tool description does not add any semantic context for the six parameters. No additional clues about how parameters interact or what values mean in context are provided.
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 analytics time series' clearly states the verb 'Get' and resource 'analytics time series', making the basic purpose understandable. However, it does not differentiate this tool from many sibling analytics tools like 'tokportal_get_account_analytics' or 'tokportal_get_video_analytics', which also retrieve analytics data. The uniqueness is only hinted by 'time series'.
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. With over 50 sibling tools including numerous analytics endpoints, the description gives no indication of scope, prerequisites, or why one would choose this tool over others like 'tokportal_get_analytics_dashboard' or 'tokportal_get_analytics_contract'.
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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, which describe safe, read-only behavior. The description adds no additional behavioral context beyond listing, but does not contradict annotations. Given annotations already cover safety, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 6 words, extremely concise with no fluff. It slightly underspecifies but is highly 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?
With no output schema, the description does not explain the return structure (e.g., paginated list, item format). Given the tool involves 5 parameters including pagination and sorting, the description omits crucial details about the response format.
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 documents all parameters. The description simply restates 'list post analytics for an account' without adding 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists post analytics for an account, using a specific verb and resource. However, it does not differentiate from sibling tools like tokportal_get_video_analytics or tokportal_get_account_analytics, which also deal with 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 over siblings, such as tokportal_get_video_analytics or tokportal_get_analytics_account. There is no mention of prerequisites or context for when listing analytics 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 already declare readOnlyHint=true and destructiveHint=false, indicating safe idempotent read behavior. The description adds no extra behavioral context (e.g., pagination behavior, what constitutes a transaction, or any side effects). With annotations present, the bar is lower, but the description could still benefit from noting pagination boundaries or date range behavior.
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 concise (two words), which aids quick scanning. It is front-loaded with the verb and resource. However, it is so minimal that it does not earn its place as a full description; an additional sentence could improve completeness without harming conciseness. Still, it avoids any 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 complexity (4 parameters, no output schema, pervasive sibling tools), the description is materially incomplete. It does not explain what a credit transaction is, what the response will contain, pagination semantics, or how the date filters interact. Since there is no output schema, the description should at least hint at return structure.
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% — all four parameters (page, date_to, per_page, date_from) have descriptions in the schema. The tool description adds no additional meaning or usage guidance for these parameters. With high schema coverage, the baseline is 3, and the description does not elevate it further.
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 credit transactions' clearly states the verb (list) and resource (credit transactions). While it distinguishes the tool from siblings like 'tokportal_get_credit_balance' and 'tokportal_get_credit_costs' by indicating a list operation, it lacks specificity about scope (e.g., all transactions or filtered). The purpose is clear but not enriched beyond the tool name.
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. Sibling tools include related credit endpoints but no comparison or context (e.g., 'Use this to paginate through credit transactions; for balance use get_credit_balance'). The description is a bare statement with no situational advice.
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, destructiveHint=false, and idempotentHint=true, so the description carries less burden. However, it adds no additional behavioral context (e.g., pagination behavior, ordering, or that it returns a list of delivery attempts). The description is neutral and 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single three-word sentence, which is extremely concise and front-loaded. However, for a tool with 5 parameters and no output schema, a slightly more detailed description would be beneficial without becoming verbose. Still, it earns a 4 for efficiency.
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 absence of an output schema, the description should explain what the tool returns (e.g., delivery status, timestamps, retry history). It also fails to mention pagination behavior or how to interpret the results. With 5 parameters and no output schema, the description is incomplete for effective 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?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no meaning beyond what the schema provides for the 5 parameters. It does not explain how parameters interact (e.g., filtering by success and event_type) or provide usage examples, but no deduction is warranted.
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 (webhook deliveries), but does not distinguish it from sibling tools like list_webhook_events or list_webhook_endpoints. The verb+resource is specific, but the lack of differentiation prevents 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 such as retry_webhook_delivery or test_webhook_endpoint. There is no mention of prerequisites, typical use cases, or exclusions, leaving the agent without context for selection.
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 only declare destructiveHint=false and readOnlyHint=false, so the description carries the burden. It adds eligibility conditions but does not disclose side effects (e.g., state changes, rate limits, success/failure responses). The tool is a write operation ('refresh'), but the description does not confirm what exactly happens or what the return value looks like, which is insufficient behavioral disclosure.
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 long, which is concise. The first sentence is almost tautological ('Refresh analytics account') but the second sentence adds important eligibility constraints. It is front-loaded with the action and resource. It could be more efficient by dropping the redundant first sentence, but overall it is reasonably 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?
The tool has 3 parameters, a nested body object, and no output schema. The description does not explain what the refresh returns, how the body parameters affect behavior, or any postconditions. Given this complexity and the absence of an output schema, the description should provide more context about the outcome and parameter usage. It covers eligibility but leaves important 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 baseline is 3. The description adds no additional meaning to the parameters—it only restates the tool's purpose. The body object's six properties have defaults and descriptions in the schema, but the tool description does not explain their semantics or how they affect the refresh operation. It neither improves nor degrades the schema-provided information.
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 'Refresh' and the resource 'analytics account' and elaborates it is 'owner-scoped through Analytics v2'. However, the first sentence is tautological, and the description does not differentiate from the sibling 'tokportal_refresh_account_analytics', which has a similar name and purpose.
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 explicit conditions under which refresh is blocked (revealed/detached, banned, inactive-Coverage accounts) and mentions that permanently grandfathered accounts remain eligible. This gives agents clear when-not-to-use guidance. However, it lacks explicit when-to-use context or comparison to alternative tools like tokportal_can_refresh_account_analytics, so it is adequate but incomplete.
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 indicate destructiveHint=true and idempotentHint=true, so the core behavioral traits are covered. However, the description adds no further context about side effects (e.g., impact on pending deliveries, required permissions) or what happens upon successful deletion. With annotations present, the bar is lower, but the description still fails to add any meaningful behavioral insight.
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 gets directly to the point with no wasted words. It is front-loaded and efficient. However, it could potentially include a bit more context (like common return status) without losing conciseness.
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 delete operation with a single required parameter, the description is minimally adequate. It covers the basic purpose but lacks details on return behavior (e.g., HTTP status code), error conditions, or any preconditions. Given the tool's simplicity and the absence of an output schema, a slightly richer description 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%, with both parameters ('id' and 'idempotency_key') described in the input schema. The tool description does not add any parameter-level information beyond what the schema already provides, so the baseline score of 3 is appropriate per guidelines.
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 ('Delete') and the resource ('a webhook endpoint'), making the tool's purpose unambiguous. This distinguishes it effectively from sibling tools like tokportal_create_webhook_endpoint, tokportal_get_webhook_endpoint, and tokportal_update_webhook_endpoint.
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 when to delete versus update a webhook endpoint. No prerequisites or conditions (e.g., ensuring no pending deliveries) are mentioned, leaving the agent without context for proper selection among sibling webhook 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 convey read-only, idempotent, non-destructive behavior. The description adds the 'delivered' qualifier, which implies a filter or state constraint not captured in annotations, but fails to elaborate on error scenarios, access requirements, or return value details.
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 concise with a single sentence that is front-loaded. However, it omits usage guidance and behavioral nuance, so it is slightly under-informative for an ideal concise description.
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 get-by-ID tool with annotations present, the description is adequate but not thorough. It does not clarify the meaning of 'delivered account,' nor does it mention the expected output or error handling, leaving gaps for an AI 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?
The input schema fully describes the single 'id' parameter with a UUID format and description 'Saved account ID.' The description adds no additional meaning about the parameter, meeting the baseline for 100% 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 states 'Get a delivered account,' using a specific verb and resource. It hints at a distinction from sibling tools like tokportal_list_accounts which list all accounts, but it doesn't explain what 'delivered' means, leaving some 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 such as tokportal_list_accounts, tokportal_get_account_analytics, or other account-related tools. The description does not mention prerequisites or context for choosing this tool.
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, so the description carries a lower burden. However, it adds no extra behavioral context, such as what happens if the ID is invalid or what the response contains. The description merely restates the purpose.
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, perfectly concise and front-loaded with the verb. Every word earns its place with no redundancy.
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 simplicity of the tool (one parameter, no output schema, annotations present), the description is minimal. It does not explain what the configuration includes, what the return value looks like, or how it relates to sibling tools. A bit more context would improve the agent's ability 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 description coverage is 100% (the 'id' parameter has a description 'Bundle ID.'), so the baseline is 3. The tool description adds no additional meaning beyond what the schema provides, but it does not detract 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 'Get bundle account configuration' uses a specific verb and resource, clearly distinguishing it from sibling tools like 'get_bundle' (which likely gets the bundle itself) and 'configure_bundle_account' (which modifies configuration).
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 when to prefer it over get_bundle or configure_bundle_account. 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.
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, read-only operation. The description does not add any behavioral traits beyond this, such as whether the list is paginated, sorted, or filtered. Since annotations cover the safety profile, the description provides minimal extra value, scoring a 3.
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 concise at three words, front-loading the purpose. Every word is necessary, but it could be slightly more informative without losing conciseness (e.g., 'List all available platforms in the system'). Still, it is efficient and to the point.
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 no parameters and no output schema, the description carries the burden of explaining what the agent will receive. It does not mention the return format, fields, or whether the list is a list of names, objects, or IDs. For a simple list tool, this is a notable gap in 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?
There are zero parameters, and the schema coverage is 100% (trivially). The description does not need to explain parameters, but it could mention the output structure. According to the rubric, 0 parameters gives a baseline of 4, and the description does not add anything beyond the schema, so 4 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 'List available platforms' clearly states the action (list) and resource (platforms), which is specific enough among the many sibling tools. However, it doesn't elaborate on what 'platforms' refers to (e.g., video platforms, analytics platforms), leaving some ambiguity about the scope. The name itself is clear, and there is no tautology.
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_countries' or other list tools. There is no mention of prerequisites, exclusions, or context that would help an agent decide when to invoke this tool. The agent must infer from the name 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds no behavioral details (e.g., what happens if no endpoints exist, pagination behavior, rate limits), but given strong annotations, the bar is lower. A 3 is appropriate as no contradictions or contradictions 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.
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 front-loads the core action. It could be slightly expanded to include a usage hint without being verbose, but it is efficient for a simple list operation.
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 is a straightforward list endpoint with no output schema, the description is minimally complete—it states what it does. However, context like pagination behavior or default sorting is missing, which could help agents understand the response format. With rich annotations, this is acceptable but not exemplary.
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% (all 4 parameters have descriptions). The description itself adds no additional semantic value beyond what the schema provides—it merely restates the tool's purpose. With high coverage, baseline is 3, and the description does not enhance parameter understanding.
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 endpoints' uses a clear verb ('List') and resource ('webhook endpoints'), distinguishing it from sibling tools like 'tokportal_create_webhook_endpoint' and 'tokportal_get_webhook_endpoint'. It could be slightly improved by mentioning that it returns a paginated list or all endpoints, but it is sufficient.
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_get_webhook_endpoint for a single endpoint, tokportal_list_webhook_events for events). There is no mention of filtering, pagination, or prerequisites (like requiring a webhook endpoint to exist), so an agent has no context for proper selection.
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 obvious: it sends a signed event and records the result. It does not disclose side effects (e.g., if the endpoint receives a real request), idempotency guarantees, error handling, or permission requirements. Annotations are also sparse (no destructiveHint or readOnlyHint), so the description carries the burden but fails to provide enough transparency.
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 only two sentences, front-loaded with the main action, and provides a concise yet complete summary of the tool's purpose. 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?
For a testing tool, the description lacks important context: how to interpret the recorded delivery result, what happens on failure, or how it fits into the webhook lifecycle. It does not mention that the endpoint must already exist or that the delivery result can be retrieved via other tools. The minimal description leaves the AI agent with incomplete information for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; both parameters have clear descriptions in the schema. The tool description adds no additional meaning or context about the parameters, so it meets the baseline of 3.
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'), specifies the event type ('webhook.test'), and the outcome ('records the delivery result'). It also distinguishes itself from sibling webhook tools (create, list, delete, retry) by focusing on testing.
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 prerequisites (e.g., endpoint must exist), use cases, or when not to use it. The context is only implied by the tool name and sibling list.
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 readOnlyHint=false (mutation) and destructiveHint=false (non-destructive). The description correctly states 'Update' (mutation) and specifies the scope of what is updated (only safe workspace fields), which aligns with non-destructive hint. However, it does not disclose additional behavioral traits such as whether partial updates are supported (e.g., only sending subset of fields), what happens to omitted fields, or if the update is synchronous or asynchronous. No contradiction with annotations is present.
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, both concise and front-loaded. The first sentence gives the core purpose, and the second adds a negative constraint (what it does not update). Every word serves a purpose with minimal redundancy. It could possibly merge the two sentences for even tighter structure, but currently it is efficient.
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 low complexity (2 parameters, straightforward mutation of specific fields, no output schema), the description is mostly sufficient. It covers the purpose and scope, but lacks details on return values or confirmation (e.g., whether the updated settings object is returned). The annotation coverage (readOnlyHint, destructiveHint) is present, so the description compensates reasonably. Still, a brief note on response behavior 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% (body and idempotency_key are described). The description does not elaborate on parameter semantics beyond the schema; it only mentions 'client-owned workspace profile fields' in general. The example fields (website, company_name, company_niche, organic_strategy) are in the schema but not in the description. With full schema coverage, the baseline is 3, and the description adds minimal extra meaning about parameters.
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 ('Update') and the resource ('safe workspace settings'). It specifies that it updates 'client-owned workspace profile fields used by Operator context', which distinguishes it from other update tools among the siblings (e.g., tokportal_update_bundle, tokportal_update_account_commenting_profile). The phrase 'safe workspace settings' is somewhat vague but is clarified by the explicit list of fields (website, company_name, etc.) not repeated in the description but inferred from the schema.
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 guidance by stating what it does not expose ('auth, role, credit, staff, or manager settings'), which implies it is for non-sensitive, client-facing profile fields. However, it lacks explicit when-to-use or when-not-to-use instructions and does not reference any sibling tools as alternatives. The justification is implied (use for updating safe profile fields, not for auth/role settings), but no direct comparisons or context are 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?
Description adds significant behavioral context beyond annotations: it explains story-specific constraints (exactly one of video_url/story_image_url, no description, verification screenshot), credit cost for story_repost_url, and coverage renewal conditions. Annotations provide idempotentHint=true and destructiveHint=false but no cost or lifecycle details, so the description fills these gaps well. No contradiction with annotations found.
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 functional but slightly redundant: the first two sentences both say 'Configure a video slot' and 'Configure a slot as ...'. Important details (story rules, coverage conditions) are present but not front-loaded in a single cohesive paragraph. Could be streamlined by merging the opening and moving the coverage block to a separate note.
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?
Description covers many domain-specific rules (story verification, renewal conditions, per-day limits) but lacks lifecycle context: it does not mention that this is part of a multi-step workflow (configure → publish/finalize) or what the return value looks like (no output schema). Given the complexity and absence of an output schema, the description is moderately complete but misses key workflow integration cues.
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 descriptions for all parameters. The tool description reiterates some constraints (like story requiring exactly one media URL and no description) but does not add substantial meaning beyond what the schema already provides. The redundancy is neutral; 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 'Configure a video slot' and specifies that a slot can be configured as video, carousel, or story. This distinguishes it from sibling tools like 'patch' or 'finalize' by using the verb 'configure', though it does not explicitly differentiate from tools like tokportal_patch_bundle_video. The resource and action are specific.
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 explicit guidance on when to use this tool versus alternatives such as tokportal_patch_bundle_video or tokportal_add_video_slots. The description does not mention workflow context (e.g., for initial slot setup vs. editing) or provide any 'use when' / 'don't use when' indicators.
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 value beyond annotations by disclosing behavioral traits: it checks coverage, may renew automatically, and if renewal fails, no mutation occurs. Annotations provide readOnlyHint=false, destructiveHint=false, but the description clarifies that mutations may happen conditionally. 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 four sentences long, which is relatively concise. It is front-loaded with the purpose, but the subsequent sentences delve into specific conditions without a clear structure. It could be more streamlined, but it is not overly 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 description explains the conditional coverage renewal logic but does not specify what the tool does beyond 'finalizing' (e.g., state changes, response). There is no output schema, and the description omits the outcome of a successful finalization. It assumes domain knowledge of 'TokPortal Coverage' and 'grandfathered' status, which may be acceptable but leaves gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for 'id', 'position', and 'idempotency_key'. The tool description adds no additional parameter semantics or usage examples, so it does not improve upon the schema. 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 'Finalize video review' which is a verb+resource, but it's vague; it doesn't clearly distinguish from sibling tools like 'finalize bundle account' or 'publish bundle video'. The additional details about coverage renewal add context but not a precise definition of what finalizing the review entails.
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 the operation (coverage must be active or grandfathered, automatic renewal possible) but does not explicitly state when to use this tool versus alternatives such as 'publish bundle video' or 'configure bundle video'. It implies usage during finalization but lacks clear guidance on 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?
The description aligns with the annotations (readOnlyHint, idempotentHint, destructiveHint) but adds no additional behavioral details such as whether the list is paginated, ordered, or what the output format is. Annotations carry the burden, so this is acceptable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence containing only necessary words. Every word contributes to the purpose, with no redundancy or filler.
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 list tool with annotations, the description is adequate but lacks information about what 'video slots' are or what the response will contain. With no output schema, additional context would help the agent understand the result structure.
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 already fully describes the single parameter (id: Bundle ID) with 100% coverage. The description adds no extra semantic value beyond what the schema provides, meeting the baseline.
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 the resource ('bundle video slots'), making the purpose unambiguous. However, it does not differentiate itself from similar sibling tools like tokportal_list_bundles or tokportal_get_bundle_video, which could cause confusion.
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. There is no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from the name 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?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds no additional behavioral context beyond the name. It does not explain what 'unpublish' means for the bundle’s visibility, associated videos, or whether the operation is reversible. With annotations present, a 3 is appropriate—adequate but lacking elaboration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence. It is not verbose, but it could be slightly more informative (e.g., hinting at the effect) without losing conciseness. Still, it earns a 4 for being to‑the‑point.
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 this is a destructive mutation with no output schema, the description should explain the effect on the bundle’s state, whether it’s reversible, and what happens to videos within the bundle. It provides none of this context, leaving the agent under‑informed 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?
Input schema coverage is 100%; both parameters (id, idempotency_key) are documented in the schema. The description adds no parameter‑specific details beyond what the schema provides. Baseline 3 is correct since schema covers all 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 'Unpublish a bundle' uses a specific verb ('Unpublish') and resource ('bundle'), clearly distinguishing it from siblings like tokportal_publish_bundle (the inverse), tokportal_delete_comment_task (different entity), and tokportal_unschedule_bundle_video (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 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. It does not specify prerequisites (e.g., bundle must be currently published), nor does it advise against using on already‑unpublished bundles or warn about irreversible effects. Sibling tools like tokportal_publish_bundle and tokportal_update_bundle are present but no comparative context 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 are largely uninformative (readOnlyHint=false, etc.), so the description bears the transparency burden. It adds one useful behavioral detail: HEIF/HEIC may be converted to JPEG. However, it does not disclose whether the upload is synchronous, size limits, error handling, or idempotency behavior despite the parameter 'idempotency_key'. The conversion note is valuable but insufficient for full transparency.
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, front-loaded with purpose, no redundant information. Every sentence is meaningful and the description is appropriately sized for a simple upload 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?
For a tool with 4 parameters and no output schema, the description covers the core action, HTTP method, return type, and a notable conversion behavior. However, it lacks guidance on required fields (bundle_id, file_path) and error conditions. Given the many sibling upload tools, more context on when to use this specific variant 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%, so the baseline is 3. The description adds context about the multipart/form-data nature and conversion behavior, which relates to file_path. It does not add explicit meaning for each parameter beyond what the schema provides (e.g., defaults, purpose enum values). The description's mention of 'returns storage details' is not in the schema but is a helpful addition.
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 an image file directly'), the resource (image file), the method (multipart/form-data), and the result (returns storage details). It also mentions a specific behavior (HEIF/HEIC conversion). However, it does not explicitly differentiate from sibling tools like tokportal_upload_image or tokportal_upload_image_from_url, though the word 'directly' hints at the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs. alternatives (e.g., upload_image_from_url, upload_image). It does not mention prerequisites, such as requiring a valid bundle_id or that file_path must be local. No when-not-to-use or exclusion criteria are 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?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so the safety and idempotency profile is clear. The description adds no behavioral detail beyond 'get configuration', but the annotations are sufficient. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of four words, which is extremely concise. It is front-loaded with the action 'Get'. It could be slightly more descriptive without losing conciseness, but it's efficient.
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 retrieval tool with complete schema coverage and robust annotations, the description is minimally adequate. It does not explain the return value (no output schema), but for a 'get' operation the concept is straightforward. However, it lacks context about what 'video slot configuration' entails or how to interpret the result.
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 explains both parameters (id as Bundle ID, position as 1-based video slot position). The description adds no further parameter context, 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 retrieves video slot configuration. The verb 'Get' and resource 'video slot configuration' are specific. However, it does not differentiate from sibling tools like tokportal_configure_bundle_video or tokportal_patch_bundle_video, which also deal with bundle videos. A clear distinction would improve the 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?
No guidance on when to use this tool versus alternatives. Among many bundle-video-related siblings (e.g., tokportal_configure_bundle_video, tokportal_patch_bundle_video, tokportal_get_bundle_video? – not a sibling), the description offers no context for selection. It does not mention prerequisites, such as needing to obtain a bundle ID or video slot position first.
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 behavioral traits: it returns a short-lived signed URL, the response contains a secret not stored in the replay ledger, and it explains why Idempotency-Key is rejected. This adds value beyond the annotations, which already indicate non-idempotent and non-read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at five sentences and front-loads the purpose in the first sentence. It could be slightly more efficient by combining the idempotency warnings into a single sentence, but it remains clear and well-structured.
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 return value and a key behavioral constraint, but it lacks context on how to use the returned URL, the effect of the 'purpose' parameter, and the overall workflow. Given the nested input schema and the presence of related sibling tools, this leaves some gaps for an AI 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 description coverage is 100%, so the schema already documents the parameters. The description adds no additional meaning to the parameters (filename, bundle_id, content_type, purpose), so it meets the baseline but does not improve understanding.
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 and resource: 'Create an image upload URL' and mentions the return value. However, it does not differentiate itself from siblings like tokportal_upload_image_direct or tokportal_upload_image_from_url, which have similar names and 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 a specific 'do not' guideline about Idempotency-Key but offers no guidance on when to use this tool over alternatives. There is no mention of prerequisites, typical use cases, or when to choose this tool over related upload 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 show readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows this is a non-read, non-destructive, non-idempotent operation. The description adds that it uses multipart/form-data and returns a public video URL. However, it doesn't disclose important behavioral traits: file size limits, accepted video formats, authentication requirements beyond typical TokPortal auth, or whether existing uploads get overwritten. The description adds modest value beyond annotations but is not comprehensive.
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 long and front-loaded with the key action. The first sentence states the purpose, the second elaborates on method and outcome. Every word earns its place. It could be slightly improved by clarifying that 'direct' means local file upload, but it's already quite efficient.
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 correctly mentions the return type (public video URL). However, it doesn't explain what bundle_id means or how to obtain it (likely from a prior tokportal_create_bundle or similar). Among 70+ sibling tools, there are several related to bundles and uploads, so more context on prerequisites (e.g., 'Bundle must exist and not be finalized') would help. The complexity is moderate, and the description is adequate but not thorough.
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 all 3 parameters have descriptions in the schema. The description mentions 'uploads multipart/form-data' which aligns with the idempotency_key parameter (used as a header) and file_path (local file). The bundle_id is described as 'Multipart form field bundle_id' in the schema. The description adds the context that these are multipart fields and that the return is a public URL, but doesn't explain the semantics of bundle_id (likely links the video to a bundle) beyond what the schema says. 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool uploads a video file directly via multipart/form-data through TokPortal and returns the public video URL. This clearly identifies the verb (upload), resource (video file), method (direct multipart/form-data), and outcome (returns public URL). It distinguishes from tokportal_upload_video (which likely handles uploads differently, possibly via URL or indirect method) and from other upload tools like tokportal_upload_image_direct. However, it doesn't explicitly name the sibling it differs from, so not 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests this is for direct video file uploads. However, it provides no explicit guidance on when to use this vs alternatives like tokportal_upload_video, tokportal_upload_image_direct, or tokportal_upload_image_from_url. It also doesn't mention prerequisites (e.g., must have a local file, need bundle_id from prior create_bundle call) or when not to use it (e.g., for images or remote URLs). The context is implied but not explicit.
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 a mutating operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that it 'approves' and 'marks finalized', which implies a state transition. However, it omits details like whether the action is reversible or what side effects occur (e.g., locking the account).
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 totaling 13 words, with no filler. It is front-loaded and every word adds value. Perfectly 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 no output schema, the description should clarify what 'finalized' means for downstream operations. It does not mention that the account may become read-only or that certain bundles might be affected. Completeness is adequate but not thorough.
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 both parameters (id and idempotency_key). The description does not add any parameter-level meaning beyond what the schema already provides, 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.
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 purpose with a specific verb ('Finalize') and resource ('account review'). It distinguishes itself from siblings like 'configure_bundle_account' and 'request_bundle_account_corrections' by focusing on approval and finalization of an in-review account.
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, nor does it mention prerequisites or postconditions. For example, it does not clarify that the account must be in 'in-review' state or that finalization may prevent further edits.
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, so the description carries a lower burden. The description simply reinforces that this is a read operation, which is consistent with annotations. No extra behavioral details are added, but 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that fully conveys the tool's purpose with no extraneous information. It is appropriately sized for a tool with no parameters.
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 and no output schema, the description plus annotations fully cover what the tool does. However, it does not hint at the return value or the scope of credit balance (e.g., current user vs. account), which could be helpful context. Still, it is mostly 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 accepts zero parameters and schema coverage is 100% (no missing fields). Thus, with no parameters to document, the description has nothing additional to explain, and a baseline of 4 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 'Get credit balance' clearly indicates a read operation to retrieve a credit balance. This verb+resource structure is specific and distinguishes it from sibling tools, although it does not elaborate on what kind of credit balance (e.g., user, account) compared to similar get/read 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?
The description provides no guidance on when to use this tool versus alternatives like tokportal_get_credit_costs or tokportal_list_credit_transactions. It lacks any mention of prerequisites, context, or exclusions, which is important when multiple credit-related tools exist.
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 that reads remain available when execution is paused and that specific fields indicate paused status, providing behavioral context beyond what annotations supply. No contradictions exist.
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 short (two sentences) and front-loaded with the core purpose. The first sentence ('List comment tasks') is slightly redundant given the tool name and title, but the second sentence adds valuable context about paused tasks and read availability. Overall efficient with minimal 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 no output schema, the description could clarify the response structure (e.g., paginated list with key fields). It mentions two response fields but omits others like total counts or sort order. Schema covers parameters well, but for a list tool with 100% schema coverage, the description provides adequate but not comprehensive 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% for all four parameters (page, status, per_page, saved_account_id), so the baseline is 3. The description does not add parameter-specific details beyond what the schema provides, mentioning only response fields (execution_blocked, execution_block_reason) rather than parameter semantics.
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 'List comment tasks. Lists owned comment tasks,' clearly identifying the verb (list) and resource (owned comment tasks). However, it does not differentiate from sibling tools like tokportal_get_comment_task or tokportal_delete_comment_task, which could cause confusion for an agent choosing among related tools.
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 that execution_blocked and execution_block_reason identify paused tasks and that reads remain available despite pauses, providing helpful context. But it lacks explicit guidance on when to use this tool versus alternatives (e.g., fetching a single task vs. listing), and no when-not-to-use or alternative recommendations are given.
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 provide readOnlyHint: true, idempotentHint: true, destructiveHint: false, which cover safety. However, the description does not disclose any additional behavioral traits such as pagination behavior, response size limits, caching, or whether the catalog is static vs dynamic. The 'public' mention is useful for auth context, but overall the description adds minimal behavioral depth 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, no wasted words. The first sentence gives the core function, and the second provides an important usage context. Every sentence serves a clear purpose. Excellent structure.
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 parameters, good annotations, and no output schema, the description is fairly complete. It covers what the tool does, what it returns (with specific elements listed), and why to use it (to inspect contracts). The only minor gap is not explicitly stating the return format (e.g., JSON array), but the enumeration of catalog components partly compensates.
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 0 parameters and schema description coverage is 100%, so the schema already fully documents the lack of inputs. The description adds value by explaining what the output contains (event types, envelope, signature scheme, example payloads), but since there are no parameters to describe, the 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 states the tool lists the webhook event catalog, including supported event types, delivery envelope, signature scheme, and example payloads. The name is clear ('list webhook events') and the description adds the specific content of the catalog. Among sibling tools, tokportal_list_webhook_endpoints and tokportal_list_webhook_deliveries are related but distinct, and this description adequately differentiates by focusing on the event catalog rather than 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 clearly states when to use this tool: 'before creating an API key' so teams can inspect webhook contracts. It also notes it's public (no auth needed). While it doesn't explicitly mention when not to use it or name alternatives, the context around webhook design phases is clear enough to guide selection away from list_webhook_endpoints or list_webhook_deliveries.
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, including coverage renewal conditions and failure behavior ('If Coverage cannot renew, no task or media mutation starts'). Annotations only provide basic hints (readOnlyHint: false), so the description carries the transparency burden and does so well, though it could mention idempotency implications of the renewal.
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?
Three sentences: first sentence clearly states the core action, followed by two sentences about preconditions. It is front-loaded and efficient. Minor deduction for the second and third sentences being somewhat dense but still necessary for transparency; could be slightly more structured.
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 core action and important preconditions (coverage/grandfathered accounts). However, with no output schema, the agent is not informed about the return value or success response. The description also does not clarify what 'schedule' patching entails vs metadata patching. Adequate but misses some completeness for a straightforward patch 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 good parameter descriptions (e.g., target_publish_date includes constraint 'Max 3 videos per day per bundle'). The tool description adds no parameter-level details beyond what the schema already provides. Baseline 3 is appropriate as the schema does the heavy lifting.
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?
Description clearly states 'Patch video metadata or schedule', which is a specific verb+resource. This distinguishes it from sibling tools like tokportal_get_bundle_video (read), tokportal_configure_bundle_video (full configuration), and tokportal_publish_bundle_video (publishing). The core purpose is immediately clear.
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 explicit guidance on when to use this tool versus alternatives. It does not mention when to patch vs configure, finalize, or other video operations. The coverage conditions are preconditions, not alternative selection criteria. Essential usage context 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 adds meaningful behavioral context beyond annotations: account must have active TokPortal Coverage or be grandfathered, potential automatic renewal at stored rate, and failure condition (if coverage cannot renew, no task or media mutation starts). This provides insights into preconditions and side effects not captured in annotations (which only mark non-read-only, non-destructive, non-idempotent).
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 and reasonably concise. The second sentence ('Publishes a fully configured bundle') slightly repeats the first, but does not significantly waste words. Information is front-loaded with purpose then conditions.
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 and two parameters, the description covers the main action and important preconditions, but fails to explain what 'publish' means in domain terms (e.g., does it make the bundle live? start scheduled tasks?), what the return value indicates, or that a readiness check (tokportal_get_bundle_publish_readiness) exists as a prerequisite. This leaves gaps for an AI 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 description coverage is 100% with both 'id' (Bundle ID UUID) and 'idempotency_key' (optional for safe retries) documented. The tool description adds no additional parameter meaning or usage tips, 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 'Publish a bundle' with the action 'Publish' and resource 'bundle', and 'Publishes a fully configured bundle' reinforces the action. Among sibling tools (create, update, unpublish, publish readiness check), this is distinct and 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 lacks explicit guidance on when to use this tool versus alternatives like creating a bundle (tokportal_create_bundle), updating (tokportal_update_bundle), unpublishing (tokportal_unpublish_bundle), or checking readiness (tokportal_get_bundle_publish_readiness). No when-not-to-use or alternative tool references are 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?
Annotations only set readOnlyHint=false, idempotentHint=false, destructiveHint=false – this is thin. The description compensates well by disclosing blocking conditions (revealed/detached, banned, inactive-Coverage), eligibility for grandfathered accounts, support for forced refresh and post import options. It also mentions idempotency_key parameter behavior implicitly. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
At 3 sentences, the description is efficient and front-loaded with the core action. Each sentence adds distinct information: what it does, key capabilities, and blocking conditions. No wasted words. However, the term 'post import options' is vague without defining what it means in context.
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 nested objects (body has 6 sub-fields), no output schema, and moderate complexity, the description covers the main refresh action and constraints but omits important details: return values, side effects (e.g., does it invalidate cached analytics?), and whether the operation is synchronous or asynchronous. For a mutation tool with no output schema, more completeness would be expected.
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 any parameter-level meaning beyond what the schema already documents (force, postLimit, forcePosts, includePosts, etc.). The idempotency_key is not mentioned in the description at all. No additional value added.
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 refreshes account analytics, and identifies itself as backward-compatible. It distinguishes itself from sibling tools like tokportal_get_account_analytics (which likely reads, not refreshes) and tokportal_can_refresh_account_analytics (which checks eligibility). The forced refresh and post import options add specificity.
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 useful blocking conditions (revealed/detached, banned, inactive-Coverage accounts) and eligibility for permanently grandfathered accounts. However, it does not explicitly guide when to use this vs. alternative tools like tokportal_refresh_analytics_account, nor does it state when not to use it or mention any required prerequisites.
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 indicate destructiveHint=true, and the description adds valuable context: the immediate blocking of work, non-refundable payments, and the conditions for reactivation costs. This goes beyond the annotation by specifying what exactly gets blocked and the financial implications, which helps the agent understand the full behavioral impact.
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, front-loaded with the title 'Pause TokPortal Coverage'. Every sentence adds distinct value: purpose, immediate effect, refund policy, and reactivation costs. No redundant or unnecessary 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?
The description covers the immediate effects and financial policy, which is adequate for a mutation tool with no output schema. However, it lacks detail on the state the account enters after pausing, whether existing settings are preserved, and the full lifecycle (e.g., what 'reactivation' entails beyond cost). This leaves some gaps for an AI 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% with both parameters (id and idempotency_key) already described clearly in the input schema. The description does not add any additional meaning or context about the parameters, so it meets the baseline but does not exceed it.
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's purpose as 'Pause TokPortal Coverage' and explains it blocks new and ongoing work. The verb 'Pause' and resource 'Coverage' are specific, but the description does not explicitly distinguish from sibling tools like get_account_managed_subscription or reactivate_account_managed_subscription, though the name and title imply it is the cancel action.
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 when reactivation is free vs costly, implying usage scenarios. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to cancel vs reactivate), nor does it mention any prerequisites or contraindications. The sibling list includes get and reactivate, but the description does not reference them.
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, destructiveHint=false, and openWorldHint=false. The description 'Get credit pricing' adds no behavioral context beyond what the annotations provide—it aligns with them but does not add value. For a read operation, this is adequate but not exceptional.
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 phrase 'Get credit pricing.' It is maximally concise with no extraneous words. Every word serves the purpose of stating the tool's functionality. There is no excess to trim.
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 parameters, no output schema, and is a simple read operation with clear annotations (read-only, idempotent, non-destructive), the description 'Get credit pricing' is sufficient for an agent to understand and invoke it correctly. It is complete within its simple context, though a bit more detail on what 'credit pricing' includes (e.g., per-unit costs, tiered pricing) could improve completeness slightly.
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 and 100% schema description coverage (since there are no parameters to describe). The description adds no parameter-level information because none is needed. Baseline for 0 parameters is 4, and the description meets that expectation by not requiring additional parameter semantics.
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 pricing' clearly indicates a read operation to retrieve credit pricing information. The verb 'Get' and resource 'credit pricing' are specific, and it distinguishes itself from siblings like tokportal_get_credit_balance (which likely returns the balance) and tokportal_list_credit_transactions (which lists transactions).
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 guidance on when to use this tool versus alternatives. Among siblings, there are related tools like tokportal_get_credit_balance and tokportal_list_credit_transactions, but the description does not differentiate usage contexts or mention any prerequisites. The purpose is implied through the name and description, but explicit guidelines are 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 explicitly states conditions (active TokPortal Coverage or permanent grandfathering, auto-renewal behavior) and the consequence of failure ('If Coverage cannot renew, no task or media mutation starts'). Annotations already mark readOnlyHint=false, so mutation is implied; the description adds valuable detail on when the mutation actually executes.
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 long, front-loads the core action, and every sentence adds meaningful information. No unnecessary words 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?
The description covers the core behavioral contract (coverage/renewal conditions) but lacks any mention of return values or error handling. Since there is no output schema, the description could help by describing typical responses. The optional idempotency_key parameter is also not addressed. Still, it is adequate for a simple publish action.
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%, and each parameter already has a clear schema-level description. The tool description adds no additional parameter-specific 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 opens with 'Publish one video slot,' which is a specific verb+resource combination. The title in annotations confirms 'Publish one video slot.' This clearly distinguishes it from sibling tools like tokportal_publish_bundle (publishes entire bundle) and tokportal_publish_all_bundle_videos (publishes all slots).
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 alternatives (e.g., tokportal_publish_all_bundle_videos for bulk publishing, or tokportal_publish_bundle for the whole bundle). It focuses on internal conditions (Coverage, auto-renewal) but offers no usage context or prerequisites for choosing this 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?
The description discloses critical behavioral traits beyond annotations: it can trigger a task or media mutation, automatically renew an active period at the stored rate, and aborts if Coverage cannot renew. This exceeds the simple readOnly/idempotent flags and gives the agent important side-effect expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the purpose. The second and third sentences pack a conditional side-effect into two clauses without 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?
For a mutation tool with no output schema, the description covers the key precondition and side-effect (task/media mutation) but doesn't describe the response format or the successful outcome details. The schema covers parameters, so the main gap is what the caller receives, but the Coverage nuance is valuable.
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 baseline is 3. The description does not add any parameter-specific guidance beyond what the schema already provides, such as the meaning of id, position, body, or fields. Thus it adds no extra semantic value.
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 'Request video corrections,' a clear verb+resource statement that distinguishes it from sibling tools like tokportal_request_bundle_account_corrections. However, it does not list the specific correction types (sound, description, video_content, video_editing) that the schema shows, nor does it contrast with similar video editing tools like tokportal_patch_bundle_video.
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 choose this tool over alternatives such as tokportal_patch_bundle_video or tokportal_configure_bundle_video. The only contextual note is the Coverage precondition, which is more of an execution constraint than a tool-selection guideline.
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 set destructiveHint=true, indicating this is a destructive operation. The description adds valuable behavioral context: it explains that coverage renewal is checked before execution, and if renewal fails, no task or media mutation starts. This goes beyond what annotations convey, giving the agent a clear understanding of side effects and failure modes.
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: three sentences, no filler. The first sentence front-loads the core action, and the following sentences add necessary conditions. Every sentence serves a purpose, making it efficient for an AI agent to parse quickly.
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 destructive tool with no output schema, the description covers the operation and critical conditions (coverage renewal). However, it omits practical details like whether the bundle must be unpublished, what the return value might be (confirmation, updated state), or how this affects publishing readiness. The agent may need to infer or test these aspects.
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 any extra semantics for the parameters beyond what the schema provides (e.g., 'Bundle ID', '1-based video slot position', 'Optional Idempotency-Key'). It neither improves nor detracts from the schema's clarity, earning a neutral 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 starts with 'Unschedule one video slot,' which clearly states the verb (unschedule) and resource (one video slot). This is specific and distinct from sibling tools like tokportal_publish_bundle_video or tokportal_configure_bundle_video, making the tool's purpose immediately understandable.
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 explicitly say when to use this tool versus alternatives. It provides conditions about account coverage that must be met, but no guidance on when to prefer this over tokportal_reset_bundle_video or other slot-related operations. The agent is left to infer usage context from the name 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?
Annotations already indicate this is a mutation (readOnlyHint=false) and not destructive or idempotent. The description adds 'Updates mutable bundle metadata' but does not disclose whether the update is partial or full replacement, side effects, auth requirements, or rate limits. Since the schema suggests a partial update (body has minProperties:1 and optional fields), the description could clarify this, but it does not. It adds minimal value 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 two sentences long, front-loaded with the core purpose, and contains no extraneous information. Every word earns its place, making it efficient and easy to parse.
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 tool with 3 parameters (including a nested object) and no output schema, the description covers the basic purpose but lacks details about the return value (e.g., what the updated bundle looks like) and how the nested body structure works. Given the large set of sibling tools, a bit more context (e.g., 'This is a PATCH-like update; returns the updated bundle') would improve completeness. The description is adequate but not fully informative.
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. The description lists the updatable fields (title, external_ref, auto_finalize_videos), which reinforces the schema but adds no new semantic meaning. The term 'mutable bundle metadata' hints that some fields are immutable, but this is not specified. Baseline 3 is appropriate as the description does not significantly compensate 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's purpose: 'Update bundle settings' and lists specific mutable fields (title, external_ref, auto_finalize_videos). This distinguishes it from sibling tools like create, get, publish, and unpublish, as it focuses on updating mutable metadata rather than creation, retrieval, or state changes.
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 through its verb and resource, but provides no explicit guidance on when to prefer this tool over alternatives. It does not mention when not to use it (e.g., for immutable fields or state changes) or reference other tools like tokportal_create_bundle or tokportal_configure_bundle_account. The usage context is clear from the name and siblings but not explicitly stated.
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 are minimal (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the burden. It adds significant behavioral context: the secret is returned only once, the successful response is never stored in the replay ledger, and idempotency keys are explicitly rejected with a specific error. This goes well beyond the annotations and helps the agent understand the sensitive 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and includes essential behavioral warnings. It avoids unnecessary repetition but could be slightly more streamlined by merging some sentences. Overall, it is well-structured for quick consumption.
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 nested parameter structure and lack of an output schema, the description partially compensates by noting that the response contains a secret (only returned once). However, it does not mention other expected response fields (e.g., endpoint ID, creation timestamp) or clarify the meaning of the events array. The idempotency behavior is well covered, but the overall picture is incomplete for an agent needing to process the return value.
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?
The schema has one required parameter 'body' with nested properties (url, events, enabled, description). Despite 100% schema description coverage claimed, only 'body' has a trivial description ('JSON request body'); the nested properties lack individual descriptions in the schema. The tool description adds no meaning to these parameters beyond their names. The agent gains no insight into what values are valid for 'url', what 'events' represent, or how 'enabled' and 'description' behave.
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 starts with 'Create a webhook endpoint,' clearly stating the verb and resource. It adds that the tool returns a signing secret once, which further clarifies the specific outcome. However, it does not explicitly differentiate from sibling tools like update or list webhook endpoints, though the name itself helps distinguish.
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 instructions: 'Store the secret to verify TokPortal webhook signatures' and 'Do not send Idempotency-Key,' including the specific error code. This gives clear context on when to use the tool and a critical constraint. However, it lacks comparison to alternative webhook tools (e.g., update vs. create) and does not mention prerequisites such as required permissions or URL validity.
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 convey the tool's safe, non-mutating nature. The description adds behavioral context by specifying that results are 'owner-scoped' and require a 'saved account,' which helps the agent understand scope and prerequisites. However, it does not disclose pagination behavior beyond the 'limit' parameter, nor does it mention potential errors (e.g., missing account). Since annotations do the heavy lifting for safety, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and to the point, using three short sentences. It front-loads the primary action and resource in the first sentence, then adds specificity (owner-scoped, saved account, tier restriction). Every sentence adds value, and there is no redundant or extraneous text. However, the second and third sentences could potentially be merged without losing clarity, earning a high but not perfect score for conciseness.
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 moderate complexity (5 parameters, all described in schema, no output schema), the description covers the essential purpose and access scoping. However, the absence of an output schema means the description could have clarified what 'raw analytics snapshots' contain (e.g., format, fields) to help the agent interpret results. The description also does not mention rate limits or potential errors. It is minimally complete but leaves gaps for an agent to fill by inference or trial.
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%, meaning all five parameters have at least some description in the schema itself (e.g., 'Saved account ID', 'query parameter to'). The tool description does not add new semantic context for these parameters—they are already labeled in the schema. The description mentions 'full analytics tier only,' which adds broader context but not parameter-specific meaning. With high schema coverage, the baseline is 3, and the description does not improve upon it.
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 identifies the action ('List'), the resource ('raw account analytics snapshots'), and the specific context ('owner-scoped stored raw analytics payloads for a saved account'). It distinguishes itself from sibling tools like 'tokportal_list_analytics_post_raw_snapshots' and other analytics retrieval tools by highlighting the raw payload nature and the requirement of a saved account. The phrase 'Full analytics tier only' adds a critical access constraint, leaving no ambiguity about the tool's 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 ('List raw account analytics snapshots') and mentions an important constraint ('Full analytics tier only'). It implicitly contrasts with sibling tools that list post-level snapshots or perform different analytics operations. However, it does not explicitly tell the agent when to avoid using this tool or suggest alternatives for cases like filtering by user or workspace, leaving some room for interpretation.
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 readOnlyHint, idempotentHint, and destructiveHint. The description adds context that this tool remains available during coverage pauses, which is valuable behavioral information 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?
Two sentences total: the first states the core purpose, the second adds crucial availability context. No filler or redundancy, every sentence earns its place.
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, and the description does not explain what the returned list of verification events contains (e.g., fields like timestamp, verifier, result). For a list tool that returns structured objects, this omission hinders an agent from fully understanding the response.
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 'Comment task ID.'). The tool description does not add any further meaning or formatting details 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 uses a specific verb ('List') and resource ('comment task verification events'), and clarifies it lists verifier attempts for one owned task. This clearly distinguishes it from sibling tools like tokportal_list_comment_tasks (lists tasks) and tokportal_get_comment_task (gets a single task).
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 states that the read remains available while TokPortal Coverage pauses task execution, implying a use case during pauses. However, it does not explicitly compare to alternatives like tokportal_get_comment_task or tokportal_list_comment_tasks, nor does it specify when not to use this tool.
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 provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. However, the description adds zero behavioral context beyond what annotations already tell the agent. It does not describe the result format, whether the list is static or could change, any pagination (unlikely with no params), or what 'countries' specifically refers to. With annotations carrying the safety burden, the description should at least add some behavioral detail about the output, but it adds nothing. Score is 1 because it fails to add any value 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 a single, short, complete sentence with zero waste: 'List available countries.' Every word earns its place, and there is no fluff, redundancy, or unnecessary detail. Perfectly concise for a trivial tool.
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 zero parameters, robust annotations (readOnly, idempotent, etc.), and no output schema, the description covers the core purpose adequately. It's a simple list operation, and the agent can infer that the output will be a list of country identifiers/names. A 4 is appropriate because while it covers the essentials, a slightly richer description (e.g., 'Returns a list of country codes and names') would improve completeness without being necessary.
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 has 0 parameters, and schema description coverage is 100% (trivially). The description's job with zero parameters is minimal; it simply needs to confirm there are no options. The description does not contradict the schema. A baseline of 4 is appropriate for a no-parameter tool where the description adds no parameter info because there are none to document.
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' is a clear, specific verb+resource statement. It immediately distinguishes this tool from its many siblings which deal with analytics, bundles, comments, video uploads, accounts, etc. – this is the only tool likely related to listing geographical data.
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 implicitly states when to use this tool: when you need to know the list of available countries. Context signals show 0 parameters, so there's no complexity. The sibling list contains many data retrieval tools, but none other reference countries, so usage is straightforward. A 4 is given because there is no explicit mention of when NOT to use it or prerequisites, but for a simple parameterless list tool, the implicit guidance is sufficient.
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 show destructiveHint: false and idempotentHint: false, which the description complements by stating the tool 'moves' an account state (a non-destructive mutation) and implicitly supports idempotency via an optional idempotency_key. However, the description does not detail what side effects occur (e.g., notifications, logs, or changes to related resources) or clarify that reviewer feedback (comment) is required. With annotations covering the safety profile partially, 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 consists of two concise sentences that are front-loaded with the core purpose. Every word is functional: the first sentence states the action, and the second defines the state transition and feedback requirement. There is no fluff 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?
The tool has a complex schema with nested objects (body, fields), 5 parameters, and no output schema. The description covers the core workflow and state transition, which is sufficient for a non-destructive correction request with good annotation coverage. However, it might benefit from briefly noting that the tool returns a bundle object or an error, but since there is no output schema, the description is reasonably complete for the use case.
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%, and the schema provides clear descriptions for all parameters, including the nested body, fields, comment, and idempotency_key. The description itself does not add new semantic information about the parameters beyond what is in the schema. For instance, it does not explain the relationship between the top-level 'fields'/'comment' and the nested 'body.fields'/'body.comment', nor does it clarify the boolean field semantics. 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 uses a specific verb ('Request account corrections') and clearly states the resulting state transition: 'Moves an in-review account back to pending corrections with reviewer feedback.' This is a succinct and unambiguous description of the tool's action, and it distinguishes itself from sibling tools like 'tokportal_finalize_bundle_account' or 'tokportal_configure_bundle_account' by focusing on the correction-request workflow.
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 this tool: when an account is in-review and needs corrections. However, it does not explicitly state when NOT to use it, nor does it reference alternative tools for similar tasks (e.g., 'tokportal_configure_bundle_account' for initial setup, or 'tokportal_fix_bundle_video_download' for video-specific fixes). The context from the schema (required 'id' and conditional 'body'/'comment') reinforces the intended usage, but the description itself lacks exclusionary 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 description reveals critical behavioral traits: irreversible first-access event, account detachment, read-only state, policy-dependent pricing, and support termination. Annotations (destructiveHint=false) are not contradicted because the tool changes state but does not destroy data. The description adds significant 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a dense wall of text with no paragraph breaks or bullet points. While each sentence is informative, the lack of structure makes it difficult to parse quickly. It could be more concise by separating policy details, error conditions, and usage restrictions.
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 (policy versioning, multiple HTTP statuses, irreversible side effects, idempotency restriction), the description covers most important aspects. It mentions the response contains a verification secret, but does not specify the exact response format (fields, structure). This is a minor gap, but overall it is quite 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 input schema already provides 100% coverage with descriptions for both parameters. The description adds context about HTTP error responses (428, 409) tied to the body parameters, and explains the effect of policy_version and acknowledge_support_forfeit, which goes 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 'Retrieve latest account verification code' and explains the context of policy-based outcomes. However, it does not explicitly differentiate from the sibling tool 'reveal_account_credentials', which could clarify when to use which tool.
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 extensive guidance on when to use this tool, including policy conditions (428, 409), the idempotency-key restriction, and the irreversible nature of the event. It implies when not to use (e.g., for old accounts that don't require new policy version), but lacks explicit exclusions.
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?
The description states the reveal is irreversible, permanently detaches the account, makes it read-only, and ends TokPortal coverage — clearly destructive behavior. However, annotations mark destructiveHint: false, creating a direct contradiction. Per guidelines, score 1 with annotation_contradiction flag.
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 verbose — multiple paragraphs with dense technical details. While no sentence is truly wasted, the structure could be improved (e.g., separating policy case logic from idempotency notes). Front-loading the core purpose is good, but length reduces clarity for quick scanning.
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 (two pricing policies, idempotency constraints, error codes) and absence of an output schema, the description covers most critical aspects: cost, prerequisites, irreversible consequences, and error handling. However, it does not describe the success response format (e.g., which fields are returned), which is a gap.
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%, baseline 3. The description adds significant context beyond schema: explains that policy_version is required only for post-cutoff accounts, details the cost implications, and clarifies that acknowledge_support_forfeit is only needed on first reveal. This enhances 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 starts with 'Reveal delivered account credentials' and thoroughly explains the action, resource, and context of credential reveal. It distinguishes itself from other tools by detailing the pricing and policy conditions tied to account creation timestamps, which no sibling tool addresses.
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 the tool based on account creation date relative to a cutoff, including prerequisites (policy_version acknowledgement) and cost conditions. It also warns against sending Idempotency-Key and advises fetching safe account state after uncertain transport before retrying.
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 minimal (no readOnly/destructive hints), so the description carries the behavioral burden. It clearly states the operation is mutative ('Approves and finalizes') and discloses a blocking condition and recovery path. It also hints at idempotency via the idempotency_key parameter. This goes beyond annotations without contradicting them.
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. The first sentence front-loads the purpose, and the last sentence adds a condition. The second sentence is somewhat redundant ('Approves and finalizes an owned manually_confirmed task'), but overall it is efficient with no extraneous 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?
Given the tool has only 2 parameters, no output schema, and sparse annotations, the description covers: the operation, preconditions (manually confirmed, owned), a blocking condition, and recovery suggestion. It does not describe the return value or error states, but for a straightforward approval action, it 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 coverage is 100%, so the description adds little meaning beyond what is already in the schema for both parameters. The description references the id parameter indirectly ('owned manually_confirmed task') but does not elaborate on formats or constraints. Baseline 3 is appropriate as the schema does the heavy lifting.
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 a manually confirmed comment task' and specifies it finalizes an owned manually_confirmed task. This provides a specific verb and resource, and distinguishes from sibling operations like dispute or delete by emphasizing the 'approved' and 'finalized' nature.
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 on when to use the tool: only for 'owned manually_confirmed' tasks and notes a blocking condition (TokPortal Coverage inactive) with a suggested recovery action. However, it does not explicitly contrast with sibling tools like tokportal_dispute_comment_task or tokportal_delete_comment_task, leaving the agent without clear guidance on alternatives.
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, idempotentHint, and destructiveHint. The description adds value by explicitly stating the tool does not mutate the bundle, settle Coverage, or debit credits, and explains the temporary blockage scenario. This deepens the behavioral understanding beyond the 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 4 sentences, front-loaded with the purpose. Every sentence contributes meaningful information, from the core function to specific blocker details and temporal caveats. It is efficient without being overly verbose, though slight tightening could be possible.
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 tool has no output schema, so the description must describe return behavior. It does so by stating it returns 'every current publish blocker' and details a specific blocker type. The context about temporary blocks and the follow-up action for managed subscriptions adds completeness. It is sufficient for an agent to understand the tool's behavior and output, though the exact return format (list vs. object) is not specified.
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 provides 100% coverage for the single parameter 'id' with a description 'Bundle ID.' The tool description does not add any additional semantics or context about the parameter (e.g., how to obtain the bundle ID). Since the schema already covers the parameter, the description adds no extra value, leaving the baseline at 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 clearly states the tool 'Check bundle publish readiness' and specifies it returns 'every current publish blocker' without mutation. The verb+resource is precise, but it does not explicitly differentiate from sibling tools like tokportal_get_bundle or tokportal_publish_bundle, though the unique read-only check behavior is implied.
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 actionable guidance, including how to interpret the MANAGED_ACCOUNT_TASK_BLOCKED blocker and a recommendation to fetch the managed subscription for authoritative state. It also notes that temporary blocks may appear until renewal is settled, giving context on when results might be misleading. However, it does not explicitly state when to choose this tool over 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 already cover readOnlyHint (true), destructiveHint (false), and idempotentHint (true), so the tool's safe, non-modifying nature is well-established. The description adds no extra behavioral context beyond confirming the tool returns the authenticated user identity. Since there are no contradictions and the annotations are comprehensive, this is a clean case where the tool's behavior is fully transparent through structured fields. A 4 is justified because the description complements annotations without overlapping.
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, concise sentence: 'Get authenticated user.' It is extremely brief and directly informative, containing no fluff or redundant information. Every word is essential. This is an exemplar of conciseness for a simple tool.
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 has no parameters, a comprehensive set of annotations, and no output schema, the description 'Get authenticated user.' is entirely complete. It tells the agent exactly what the tool does: it retrieves the current authenticated user. The context is low-complexity, and nothing important is missing for selection and invocation. The completeness is excellent.
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 zero parameters, and schema description coverage is 100%. The description 'Get authenticated user.' does not need to elaborate on parameters since there are none. By the scoring guidelines, with no parameters and high schema coverage, the baseline is 4, but the description adds no semantic enrichment beyond the schema—it's just a restatement. A 3 is appropriate as the description is minimal but adequate for a param-less tool.
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 authenticated user.' clearly states the action (get) and the resource (authenticated user). It is a distinct capability among the many sibling tools, many of which deal with analytics, bundles, accounts, etc., so it stands out as a simple identity query. However, it does not explicitly differentiate itself from any similarly named tool (none are similar), so it loses the perfect score.
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 tool has no parameters and minimal side effects, so the absence of explicit when-to-use guidance is acceptable. Its purpose is self-explanatory as a basic 'who am I' call, which is implied by the name and description. However, it does not mention when not to use it or provide alternative tools for related user data (no siblings directly compete), so the score is minimally adequate.
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 annotations by explicitly stating the operation is not idempotent (header rejection), that the response contains a secret not stored in the ledger, and that the request is sensitive. Annotations only show readOnlyHint=false and idempotentHint=false, but the description adds critical detail about behavior (secret handling, ledger exclusion). 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 four sentences, each adding unique value: purpose, return value, critical usage note, and error condition. No superfluous information. Front-loaded with purpose. Succinct and efficient.
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 no output schema, the description adequately mentions return type (token and URL) and notes the secret is not stored. It also covers an important error case. However, it does not specify behavior when required fields are missing or describe the role of each input field. Since the schema covers parameter names and types, the description is fairly complete for a creation 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% (body described as 'JSON request body'), but individual parameter descriptions are absent. Property names (to, from, query, title, etc.) are self-explanatory. The description adds no additional semantic meaning beyond what the schema provides. Baseline 3 is appropriate 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 clearly states the tool creates an analytics web report, specifying it is shareable, returns a token and URL. This distinguishes it from sibling tools like tokportal_export_analytics_report_html (which exports an existing report) and tokportal_get_analytics_series (which retrieves series data). However, it does not explicitly differentiate from other creation tools like tokportal_create_video_ad_code_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 provides a key usage constraint: 'Do not send Idempotency-Key' with explanation of the error response. This is helpful but does not guide when to use this tool versus alternatives, such as when a shareable URL is needed vs. an export. The guidance is narrow and lacks context for choosing among 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 indicate a mutation (readOnlyHint=false, destructiveHint=false). The description adds that execution is conditional on coverage status, which is useful context beyond annotations. However, it does not detail side effects, reversibility, or authorization requirements, so the transparency 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?
Two sentences, 32 words. The first sentence defines the core action, the second adds a critical precondition. No fluff, front-loaded, every sentence 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?
For a tool with 3 parameters, nested body, and no output schema, the description covers the state change and a key blocking condition. It could elaborate on what 'owned' means or typical success response, but overall it is sufficient for understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to add parameter details. It provides no additional meaning beyond what the schema already states for id, body, and idempotency_key. 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 'Dispute' and the resource 'manually confirmed comment task', distinguishing it from siblings like approve, create, delete. The state transition 'returns to pending corrections' further clarifies the action.
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 execution is blocked (TokPortal Coverage inactive) and provides a precondition: inspect MANAGED_ACCOUNT_TASK_BLOCKED and reactivate a recoverable account first. It does not explicitly compare to siblings, but the conditional guidance is valuable for correct usage.
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 value beyond annotations by stating the tool is free and does not charge credits, and clarifies the input size limit (max 1000 characters). Annotations only indicate readOnlyHint: false (mutation) and destructiveHint: false, so the description provides useful cost and constraint context. However, it does not describe the output structure or error behaviors, and the return format is implied but not explicit.
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 with no redundancy. The first sentence states the primary action, the second adds constraints and cost, and the third provides actionable downstream usage. Every sentence earns its place, and critical information is front-loaded.
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 and absence of an output schema, the description covers purpose, input constraints, platforms, cost, and how to use the result. It omits the format of the generated terms (e.g., list of strings) but provides enough context for an agent to invoke correctly and pipeline the output. Sibling tools are many but not directly relevant, and the description sufficiently orients the 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% with descriptions for all parameters (text, count, platform, idempotency_key). The description adds minimal extra meaning beyond the schema, restating the text limitation and platform context. Per the baseline for high coverage, a score of 3 is appropriate as the description does not enhance understanding of parameters significantly.
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 generates Advanced Niche Warming search terms from a free-text niche description, specifying the verb 'Generate' and the resource 'Advanced Niche Warming search terms'. It distinguishes itself from sibling tools by focusing on niche target generation and explicitly linking to downstream endpoints like advanced_warming_terms and search_terms, which are absent in other sibling names.
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 explicit guidance on when to use the tool by stating the output should be passed to 'advanced_warming_terms' or 'search_terms' for specific workflows (bundle creation, rewarm). It also notes the platforms (tiktok, instagram). However, it does not explicitly state when NOT to use this tool or contrast it with alternatives like tokportal_configure_bundle_warming_terms, leaving some room for ambiguity.
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, setting a strong baseline. The description adds meaningful context about ownership scope ('owned comment task') and business logic (blocking due to inactive TokPortal Coverage, stable block reason), which enriches agent understanding beyond the structured 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 consists of two concise sentences with no wasted words. It is front-loaded with the action ('Get a comment task') and efficiently states the return content. Every sentence contributes 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?
For a simple one-parameter retrieval tool with strong annotations and no output schema, the description adequately covers the function and key return fields. It could mention error handling (e.g., behavior when ID is invalid or task not owned), but this is a minor gap. Overall, it provides sufficient context for an agent 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?
The input schema has 100% coverage with a clear description for the `id` parameter ('Comment task ID.'). The tool description does not add any further parameter-level details (e.g., how to obtain the ID, constraints, or format nuances). With full schema coverage, the 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 'Get a comment task' and specifies that it returns a single owned comment task with specific properties: inactive TokPortal Coverage blocking status and stable block reason. This effectively distinguishes it from sibling tools like tokportal_list_comment_tasks (list) and tokportal_get_comment_pulse (different data). The verb+resource pattern is precise and unambiguous.
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 usage scenario (fetching a single comment task to check blocking state) but does not explicitly state when to use this tool versus alternatives like tokportal_list_comment_tasks, tokportal_approve_comment_task, or tokportal_dispute_comment_task. No guidance on prerequisites or exclusions 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?
Annotations provide only readOnlyHint=false and destructiveHint=false, giving minimal behavioral context. The description compensates richly: it details screen-recording per term, verification before completion, standard credit rate (5 credits per term), the split over 3 days, and even the legacy grace window closure. All this adds significant 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of ~150 words. It front-loads the purpose, but includes tangential details like the legacy grace window and credit cost reference that could be moved to parameter descriptions or annotations. While efficient, it is not as concise as it could be with bullet points or separation of prerequisites from behavior.
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 thoroughly covers prerequisites, behavior, and scheduling, but it fails to mention what the tool returns (e.g., session ID, status). Since there is no output schema, the agent is left guessing about the tool's response. This is a notable gap for a tool that initiates a long-running process, reducing 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?
The input schema already has 100% coverage, with detailed descriptions for 'search_terms' including the behavioral process. The tool description partially repeats that process (e.g., 'for each provided term the manager screen-records...') but does not add new parameter-specific semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Order Advanced Niche Warming (rewarm) on a delivered account.' It immediately distinguishes this tool from siblings like tokportal_generate_warming_terms (which generates terms) and tokportal_list_account_warming_sessions (which lists sessions), as it is the only one that starts a warming session on a delivered 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 lists explicit prerequisites (active TokPortal Coverage, routable account manager, non-cancelled support order, TikTok/Instagram, no active warming session) and notes that a completed bundle remains eligible. It also explains the scheduling (3 calendar days, earlier-day tasks available). While it does not explicitly say 'do not use if X', the prerequisites effectively guide when to use versus alternatives like generating terms or configuring bundle warming terms.
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 minimal (readOnlyHint false, destructiveHint false) and the description adds significant behavioral context: preconditions (account ownership, active coverage), state-based restrictions (read-only for revealed/detached, banned, etc.). This goes beyond the structured hints.
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?
Four sentences, each serving a purpose: title, action, precondition, exclusions. No fluff, front-loaded with the core purpose. Highly efficient.
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 (3 parameters, nested object, no output schema), the description covers input conditions and restrictions well. It lacks explicit mention of return value or whether the update is partial vs full replacement, but overall 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 coverage is 100% so the schema already documents each parameter. The description adds overall context ('commenting/autopilot profile fields') but does not elaborate on individual parameter semantics. 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 'Update' and the resource 'account commenting profile', and further specifies 'client-owned commenting/autopilot profile fields for a delivered account'. This distinguishes it from siblings that deal with analytics, bundles, or other account aspects.
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 implicit usage context (account must belong to API key owner, have active TokPortal Coverage, and certain states are read-only) but does not explicitly mention when to use this tool over alternatives or name other tools for similar tasks. It lacks comparative 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?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds key behavioral context: the Coverage preflight, auto-renewal possibility, and that no mutation occurs if renewal fails. This goes beyond the annotation data.
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 purpose: the first states the action, the second explains the coverage requirement, the third covers renewal and failure behavior. No extraneous 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?
While the description covers the coverage and batch aspects well, it does not clarify the relationship with sibling tools like tokportal_add_video_slots (e.g., does this configure already-added slots or add+configure?). The absence of any mention of what 'configure' means in the slot lifecycle leaves a gap, given 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 all parameters documented inline. The description adds no additional parameter-level 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 clearly states 'Configure video slots in bulk' and explains the batch nature with a single Coverage preflight. It distinguishes itself from singular sibling tools like tokportal_configure_bundle_video by emphasizing bulk and the preflight step.
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 prerequisites (active Coverage or permanent grandfathering) and conditions for auto-renewal and failure. It does not, however, directly compare with alternatives like tokportal_configure_bundle_video (singular) or indicate when to choose this batch variant over them.
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 (readOnlyHint=false, etc.) by detailing atomicity, credit debiting, rolling capacity checks, contract_bundle_allowance, deterministic order, rollback behavior, and the handling of external_ref and idempotency_key. This provides rich behavioral insight that is essential for correct usage.
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 lengthy and contains detailed information that is valuable but not tightly structured. It is front-loaded with the main purpose, but the multiple paragraphs could be more concise. Some details, like advanced warming options, might be better placed in the schema or separate documentation.
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 many aspects of the tool's behavior (atomicity, credit costs, advanced warming), but it does not describe the return value or response format. Given the complexity and absence of an output schema, this omission is a gap. Error handling is mentioned only briefly (rollback on failure).
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 baseline is 3. The description adds some extra meaning, such as the batch-level nature of external_ref and the idempotency_key usage, but most parameter details are already covered in the schema. The description does not significantly enhance parameter understanding 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 'Create bundles in bulk. Creates and pays several bundles in one atomic creation checkout.' This is a specific verb (create) and resource (bundles in bulk), and it distinguishes from the sibling tool tokportal_create_bundle by emphasizing atomic bulk creation.
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 for when to use the tool, including details about the atomic batch, credit consumption, and advanced warming options. It implies the tool is for multiple bundles, but does not explicitly state when not to use it or compare with alternatives like tokportal_create_bundle. The guidance is clear but could be more direct.
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 that a due active period may renew automatically, and that if coverage cannot renew, no mutation occurs. This conveys important side effects and failure modes. However, it does not mention that the operation is not idempotent (despite the idempotency_key parameter) or discuss retry safety.
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 earning its place. The first sentence states the primary action, the second adds preconditions, and the third explains a conditional side effect. No redundancy or 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's complexity (4 parameters, nested body, no output schema), the description covers the core operation and preconditions but is incomplete regarding return values. It does not describe what the response contains (e.g., success indicator, updated bundle data) or error scenarios beyond coverage renewal failure. An output schema would reduce the need for such detail, but none is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add substantive meaning to the parameters beyond what the schema already provides. It mentions 'manager-flagged broken video or carousel download URL' which hints at the body structure but does not clarify position, id, or idempotency_key semantics.
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 purpose: fixing a broken video download by replacing a manager-flagged URL and clearing the download issue flag. This is a specific verb+resource combination that distinguishes it from sibling tools like configure_bundle_video or patch_bundle_video, which address different aspects of bundle video management.
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 this tool should be used: only when a download is manager-flagged as broken. It also specifies prerequisites (account must have active TokPortal Coverage or be grandfathered) and describes automatic renewal behavior. However, it does not explicitly mention when NOT to use it or name alternative tools, missing a chance to guide selection among the many bundle video tools.
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 behavioral detail by enumerating the returned data: 'Analytics v2 contract, current access payload, metric semantics, freshness targets, and redaction rules.' This goes beyond the annotations to describe the output structure, though it does not cover auth requirements or potential side effects (irrelevant here).
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: the first defines the action and resource, the second lists the return contents. Every word carries value, no repetition, and the structure is front-loaded with the essential purpose. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description completely informs the agent of what the tool does and what it returns. It covers the return categories sufficiently, leaving no ambiguity about the tool's function. No additional information is needed.
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, and schema coverage is trivially 100%. The description adds no parameter information because none exists. For a parameterless tool, a baseline of 4 is appropriate as the description focuses on the return value instead.
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 analytics data contract, listing specific components (contract, access payload, metric semantics, freshness targets, redaction rules). The verb 'Get' and resource 'analytics contract' are unambiguous and differentiate it from sibling tools like tokportal_get_analytics_series or tokportal_get_analytics_account, which focus on different analytics aspects.
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 sibling analytics tools (e.g., when to use get_analytics_contract vs get_analytics_series). It only states what it returns, leaving the agent to infer usage context without explicit selection criteria or alternative suggestions.
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 indicate non-read-only (readOnlyHint: false) and non-idempotent (idempotentHint: false), so the bar is lowered. The description adds crucial behavioral context: coverage checks happen before media fetching, renewal automates at stored rates, and no mutation occurs if 'Coverage cannot renew'. This goes beyond what annotations alone provide.
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 four sentences, front-loading the core action. Each sentence adds value: import process, coverage check, renewal requirements, failure handling. Minor point: the last two sentences could be slightly more concise ('A due active period can renew automatically...' is somewhat verbose).
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 tool has 4 parameters, no output schema, and is complex (CSV handling, media fetching, coverage checks). The description adequately covers the workflow and guardrails (coverage, renewal). It doesn't explain return behavior (e.g., success/failure response), but since there's no output schema, the description could be improved by mentioning what the agent can expect after execution.
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 meaning to individual parameters (e.g., what 'auto_publish' does under the hood, or how 'idempotency_key' interacts with the process). It remains generic about the overall workflow without enhancing 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 uses specific verbs ('Import', 'Uploads', 'downloads', 'configures') and names the resource ('video slots from CSV'). It clearly distinguishes from siblings: 'tokportal_publish_bundle' and 'tokportal_list_bundle_videos' focus on publishing or listing, while this tool handles the import and configuration from a CSV file.
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 (importing video slots from CSV) and outlines prerequisites and behaviors (bundles must have active TokPortal Coverage or be grandfathered, automatic renewal details). However, it does not explicitly mention when NOT to use this tool or suggest alternative tools for related tasks like batch configuration ('tokportal_batch_configure_bundle_videos').
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, destructiveHint, idempotentHint. The description adds behavioral traits: tasks 'unlock over 3 calendar days in the manager's timezone' and 'do not expire', and describes the response contents. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load the purpose, then expand with content and timing details. No wasted words, every sentence adds value.
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 a single parameter, full schema coverage, no output schema, the description covers output structure (tasks, reports, proof links, session report), ordering, and task unlock/duration behavior. Complete for a list 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 one parameter ('id') described as 'Saved account ID.' The description reinforces that it's for an account you own, adding marginal context, but does not provide additional constraints or format details 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 'Lists Advanced Niche Warming sessions for an account' with specific ordering (newest first) and details on included content (tasks, reports, proof links, session report). This distinguishes it from siblings like 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?
It mentions the context 'for a saved account you own', implying ownership requirement, but does not explicitly state when to use this tool versus alternatives like tokportal_get_warming_session or tokportal_generate_warming_terms. No when-not or alternative naming 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?
The annotations already indicate the tool is not read-only (readOnlyHint: false), not idempotent, and not destructive (destructiveHint: false). The description goes well beyond by revealing critical behavioral traits: the dependency on Coverage account state, automatic renewal of due active periods, and the conditional halting of mutations if renewal fails. It also describes inputs (bundle ID) and idempotency support (via idempotency_key), adding value 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 concise, consisting of three sentences that front-load the core action and then add necessary business context. Every sentence serves a purpose, but the second and third sentences could be streamlined slightly (e.g., 'A due active period can renew automatically...' is somewhat dense). No wasted words, but tightness could be improved.
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 (publishing all videos with business logic such as Coverage and renewal), the description covers the essential behavioral context. There is no output schema, so the agent must infer success/failure from the description's mention of 'no task or media mutation starts' on failure. The description could be more complete by hinting at what happens upon success (e.g., return of status or task IDs), but it is largely sufficient for an agent to decide when and how to invoke it.
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 coverage is 100%, so the schema already documents that 'id' is a required UUID and 'idempotency_key' is an optional string. The description does not add new parameter details beyond what the schema provides (e.g., format of idempotency_key, valid values). With full schema coverage, the baseline is 3, and the description does not elevate above that for parameter semantics.
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 ('Publish all configured videos') and the target ('on an active bundle'), using a specific verb and resource. It distinguishes this tool from the sibling 'tokportal_publish_bundle_video' (single video) and 'tokportal_publish_bundle' (bundle-level publish?), by implying a bulk operation on all video slots. The inclusion of business logic (Coverage, grandfathering, renewal) further clarifies its scope.
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 when to use this tool: when you want to publish all videos on an active bundle, and it highlights a key prerequisite—the bundle's resolved account must have active TokPortal Coverage (or be grandfathered). However, it does not explicitly mention when *not* to use it or directly contrast with siblings like 'tokportal_publish_bundle_video' for targeted publishing. The hints on renewal behavior provide useful context for when the tool might not proceed.
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 provide idempotentHint=true and destructiveHint=false. Description adds critical behavioral detail: one-shot configuration that cannot be changed, behavior at different account statuses, prerequisites for Coverage and grandfathering, and what happens if Coverage cannot renew. 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?
Front-loaded with core purpose. Each sentence adds value, but the description is lengthy with domain-specific details about Coverage renewal that could be trimmed. Still well-structured and informative.
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?
Covers input requirements and behavioral outcomes well, but lacks any mention of the return value or response format. Since no output schema exists, the description should provide minimal output expectations. Adequate but not fully 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 detailed parameter descriptions. The tool description repeats the exact count requirement and one-shot nature but adds only marginal context (deferred configuration, sibling comparison). Baseline 3 is appropriate as the schema already carries the load.
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?
Clear verb ('Configure') and specific resource ('niche targets of a count-only Advanced Niche Warming purchase'). Notes 'deferred configuration' which distinguishes from other warming tools. Sufficiently differentiates from siblings like configure_bundle_account and configure_bundle_video.
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 context: must provide exactly the purchased number of targets, one-shot limitation, and comparison with 'PUT /bundles/{id}/account' (a sibling). Explains when warming session starts. Does not mention other alternatives like tokportal_generate_warming_terms, but the comparison is sufficient for core usage.
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, idempotentHint, and destructiveHint as false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations by explaining that the `code` field remains null until the request reaches `in_review` or `finalized` status, which informs polling behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise, front-loaded sentences. Every sentence provides essential information: the core purpose and the critical detail about null behavior. No redundant or unnecessary 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's simplicity (single parameter, no output schema), the description is nearly complete. It explains the polling nature and the null field behavior. It does not cover error conditions or rate limits, but for a straightforward read-only retrieval tool, this is 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% with a single required `id` parameter described as 'Video ID.' The tool description does not add any additional semantics or constraints beyond what the schema already provides, so no extra value is added. 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' and specifies it returns the latest ad code request. The verb 'get/poll' and resource 'ad code for a video' are precise, and the sibling tool `tokportal_create_video_ad_code_request` provides contrast, making the 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies polling by mentioning that the `code` field is null until the manager submits or it is delivered, indicating repeated use to check status. While it does not explicitly list when not to use or alternative tools, the context of a single retrieval tool alongside a create tool makes the usage clear.
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 agent knows this is a safe, non-destructive read. The description adds no additional behavioral context about authentication needs, rate limits, or data freshness, but given that annotations already cover the safety profile well, the bar is lower. The description does not contradict annotations, and a score of 4 reflects that the description adds reasonable clarity beyond the bare 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, clean sentence: 'List comments for an account post.' It uses exactly 6 words, no filler, and front-loads the action and object. Every word carries meaning, efficiently conveying the tool's 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?
Given that there is no output schema, the description could hint at the return format (e.g., 'returns comment objects') but doesn't. However, the tool's complexity is low (simple list operation), and annotations plus schema sufficiently cover input details. The description, while brief, is complete enough for the agent to infer that the tool lists comment data for a specific post within an account, which aligns with the tool's likely domain.
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 100% description coverage, so the schema already describes all parameters (id: 'Saved account ID.', limit: 'query parameter limit', postId: 'query parameter postId', trackedPostId: 'query parameter trackedPostId'). The description adds no further parameter semantics beyond 'List comments for an account post', which implies the id and postId refer to the account and post. With high schema coverage, baseline is 3, but the description's concise context—tying parameters to 'account post'—earns a slight boost to 4.
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 comments for an account post' clearly states the verb (List) and resource (comments for an account post). The tool name includes 'analytics_account_comments', which aligns with this purpose. Among siblings, tools like tokportal_get_analytics_series or tokportal_get_comment_pulse suggest data retrieval but not specifically comments for an account post, so this description effectively distinguishes the tool.
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 a simple list operation for comments tied to a post within an account. However, it provides no explicit guidance on when to use this tool versus alternatives like tokportal_get_comment_pulse (which might summarize comment sentiment) or tokportal_list_comment_tasks (which might deal with moderation tasks). The context of 'account post' differentiates it somewhat but lacks explicit when-to-use or when-not-to-use instructions.
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, idempotentHint, and non-destructive. The description adds important context: it returns 'owner-scoped' data, is for 'stored raw analytics payloads', and requires 'Full analytics tier'. This goes beyond annotations by clarifying data scope and access prerequisites. 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?
Three sentences, each carrying essential information: what it returns, scope, and tier requirement. No filler 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?
Given no output schema and simple filters, the description covers primary purpose and constraints. Missing details: pagination behavior, whether empty results are possible, or interaction of filters. But overall sufficient for a read-only listing 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 does not provide additional parameter-level semantics (e.g., format details for `to`/`from` or interaction between filter parameters). 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 uses specific verbs ('List') and nouns ('raw post analytics snapshots'), and clarifies the scope ('owner-scoped stored raw analytics payloads for a tracked post'). It also specifies the tier requirement ('Full analytics tier only'), which distinguishes it from broader analytics tools 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for listing stored raw snapshots for a tracked post, and the sibling list includes `tokportal_list_analytics_account_raw_snapshots` for account-level snapshots. The tier restriction is explicit. However, it does not state when not to use it (e.g., if you need computed analytics) or explicitly name alternatives.
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 clearly discloses that it's a write operation ('resends'), uses a fresh signature, and preserves the event ID for idempotency. Annotations show readOnlyHint=false and destructiveHint=false, aligning with the description. The description adds value by explaining the behavior of the signature and event ID preservation 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 exceptionally concise: three sentences, each adding value. The first sentence states the action, the second explains what happens, and the third clarifies a key behavioral detail (idempotency). Zero wasted words.
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 no output schema and moderate complexity, the description covers the core purpose and behavior. It lacks details like response format (e.g., whether it returns the new delivery object) or error scenarios, but the key mechanics are clear. The description is sufficient for an agent to understand the tool's function.
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 three parameters. The description adds context by explaining that the event ID is preserved (implying idempotency_key's role) and that the payload is resent to the current URL, which relates to the id parameter. It adds value to the schema without repeating it.
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 ('Retry'), the resource ('a webhook delivery'), and the specific action (resends stored payload with a fresh signature). It distinguishes itself from siblings like tokportal_list_webhook_deliveries and tokportal_test_webhook_endpoint by focusing on retrying an existing failed delivery.
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 resending webhook payloads but does not explicitly state when to use this vs alternatives like test_webhook_endpoint or manage deliveries. It lacks guidance on prerequisites (e.g., endpoint must exist) or scenarios where this is inappropriate. The idempotency context is helpful 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 already set readOnlyHint=false, idempotentHint=false, and destructiveHint=false, indicating a non-read, non-idempotent, non-destructive mutation. The description confirms it's a write operation ('stores it permanently'). However, it doesn't clarify whether the same URL can be imported multiple times (dedup behavior), what happens on fetch failure, whether the tool blocks or returns errors for non-image URLs, or any rate limits. With annotations providing baseline safety info, a 3 is appropriate—adds some context but doesn't fully disclose 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences: the first states the purpose, the second elaborates on the mechanism and outcome. Every word is informative with no filler. Front-loaded with verb and resource. Perfectly sized for quick comprehension.
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 tool has 2 parameters with full schema coverage, clear annotations, and a straightforward purpose. The description explains the core behavior (fetch then store) and parameter expectations (public direct image URL). With no output schema, the description doesn't detail return values (e.g., uploaded image ID or URL), which is a minor gap. However, given the tool's simplicity and the richness of sibling context, the description is nearly complete. A 4 reflects the minor output documentation gap.
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 value by implying that the 'url' parameter must be a 'public direct image URL', emphasizing accessibility and format. 'purpose' has enum values in schema but description doesn't elaborate; however, for a 2-param tool with comprehensive schema documentation, the description's added context (especially around URL) merits an above-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 'Import an image from URL' with specific verb 'Import' and resource 'image'. It explicitly distinguishes itself by sourcing from a URL ('Fetches a public direct image URL'), contrasting with siblings like 'tokportal_upload_image' (likely from local file) and 'tokportal_upload_image_direct' (different method). This makes the purpose 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly communicates when to use: when you have a public direct image URL to fetch into TokPortal storage. The sibling names 'tokportal_upload_image' and 'tokportal_upload_image_direct' provide alternatives for other sources/methods, but no explicit when-not-to use guidance or prerequisites (e.g., image format restrictions, size limits, URL accessibility checks). Clear context but lacks exclusions.
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 indicate idempotentHint=true and destructiveHint=false. The description goes beyond by explaining that the account must have active TokPortal Coverage (or be grandfathered), that a due active period can renew automatically, and that if Coverage cannot renew, no task or media mutation starts. This adds significant behavioral context not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is written in a dense but efficient paragraph. Every sentence adds value: purpose, backward compatibility, alternative recommendation, conditions, and failure behavior. It could be slightly more structured (e.g., separated conditions), but overall it is concise for the amount of information conveyed.
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 body, multiple optional fields, Coverage dependency, pre/post-delivery states), the description covers the main behavioral aspects. However, it does not specify what the tool returns (no output schema) or error scenarios, which are minor gaps. Overall adequate for a configuration tool but could be more 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 the baseline is 3. The tool description does not add meaningful parameter-level detail beyond what the schema already provides (e.g., the biography max length is already in the schema). The description mentions some parameters (username, visible_name, etc.) but does not clarify usage beyond 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 tool configures a bundle account profile, specifying the exact identity fields (username, visible name, biography, profile picture). It distinguishes itself from siblings by mentioning the recommended alternative endpoint for warming terms, implying separation from tokportal_configure_bundle_warming_terms.
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 recommends PUT /bundles/{id}/warming-terms as an alternative for setting warming terms, and provides conditions for when the tool works (Coverage active or grandfathered, new accounts pre-delivery). It does not explicitly list exclusions or directly compare to other siblings, but the alternative guidance is strong.
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 extensively discloses behavioral traits not covered by annotations: immediate credit debit, server-side cost calculation, allowance slot consumption, auto-cancellation of unconfigured warming terms, refund policies, and the distinct roles of external_ref and idempotency_key. This goes far beyond the minimal annotation set (readOnlyHint=false, etc.) and fully informs the agent about side effects and guarantees.
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?
Despite being long, every sentence carries essential information. The description is front-loaded with the core action ('Create a bundle') and then logically flows through payment, credit costs, allowance details, warming options, and idempotency. No superfluous text; it is as concise as complexity demands.
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 (nested body, multiple conditional fields, business rules around credits and refunds) and the absence of an output schema, the description covers nearly every aspect needed for correct invocation: creation types, payment timing, cost calculation, advanced warming configuration, auto-cancellation, and duplicate detection. It is complete enough for an agent to use without guessing.
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 provides 100% coverage with detailed parameter descriptions, so the baseline is 3. The tool description adds significant overarching context (credit debit timing, allowance consumption, auto-cancellation, cutoff for free trial) that enriches understanding of why parameters behave as they do, though it does not describe individual parameters in new detail. This elevates the score to 4.
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 'Create a bundle' and elaborates on three distinct bundle types (account-only, account-and-videos, videos-only), making the tool's purpose very specific. While it doesn't explicitly differentiate from sibling tools like tokportal_create_bundles_bulk, the naming convention and detailed type descriptions suffice to identify this as the tool for single-bundle creation.
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 explicit guidance on when to use this tool versus siblings or alternatives. It does not mention when not to use it, nor does it reference other tools for different scenarios (e.g., bulk creation, publishing, updating). The internal guidance on bundle types is about configuring the request, not tool selection.
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 mark readOnlyHint, idempotentHint, and destructiveHint, but the description adds critical behavioral details: the recorded_status lag at period_end, validity of zero-credit quotes, and the multiple interpretations of a missing record (grandfathered vs. not eligible vs. not yet delivered). This fully informs the agent of edge cases and temporal behaviors.
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 covers nuances efficiently. While it is longer than strictly necessary, every sentence adds value and no content is redundant. Could be slightly tighter but is well-structured for an agent to parse.
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 no output schema, the description explains the return fields effectively and covers important edge cases (grandfathering, 404 interpretation, period transitions). It is nearly complete but could mention the data type or structure of the 'reactivation quote' for full clarity.
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 single parameter 'id' has 100% schema description coverage ('Saved account ID.'). The description adds no additional semantic detail about the parameter format or constraints beyond mentioning 'one eligible saved account', which is implicit. With high schema coverage, 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 tool retrieves TokPortal Coverage status and lists the specific data returned (status, period, rate, etc.). It distinguishes itself from sibling tools like tokportal_reactivate_account_managed_subscription and tokportal_cancel_account_managed_subscription, which are mutation operations, making the read-only 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides substantial context about when to use this tool, including handling of grandfathering, 404 responses, and timing nuances at period boundaries. However, it does not explicitly compare to alternatives beyond the implicit distinction from reactivation/cancellation tools, and could be more direct about situations where this tool should not be used.
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 rich behavioral context beyond sparse annotations: it discloses that 7 credits are debited, atomicity of assignment/debit/task creation, and the one-open-request-per-video constraint. No contradiction with annotations (readOnlyHint=false, destructiveHint=false are consistent with a mutation 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?
Every sentence adds value: purpose, prerequisites, eligibility, atomicity, polling instruction. Well-structured and appropriately sized with no wasted words. Front-loaded with the main action.
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 3-parameter tool with no output schema, the description covers prerequisites, side effects, eligibility, and follow-up action. Minor gap: no mention of error handling when prerequisites fail, but overall quite 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%, so baseline is 3. The description adds minor practical context (note is to manager for campaign, platform defaults to video's platform) but does not significantly enhance beyond the schema descriptions. Adequate but not extra.
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 requests an ad code for a finalized video, specifies the resource (TikTok Spark Code or Instagram Partner Code), and includes constraints like finalized video and platform requirements. It distinguishes from siblings like tokportal_get_video_ad_code_request and other video management 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 explains prerequisites (active TokPortal Coverage, routable manager), eligibility rules (completed bundles eligible, cancelled never restored), and explicitly advises polling the GET endpoint for code retrieval. However, it does not explicitly list when NOT to use the tool or compare to alternatives beyond the GET endpoint.
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, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: tasks remain open until completed and do not expire, and dispatches occur in the manager's timezone. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and every sentence adds value. No wasted 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?
No output schema exists, so the description must convey return structure. It does so with specific details on status, per-term tasks (including dispatch, verification, links), and aggregated report. Could be more precise about the exact fields, but sufficient for selection and 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?
The input schema has 100% description coverage for the single parameter 'id' (described as 'Warming session ID.'). The description does not add any additional meaning or constraints beyond what the schema already 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 'Get' and the resource 'Advanced Niche Warming session'. It details what is returned (status, per-term tasks, aggregated report), distinguishing it from sibling list tools like 'tokportal_list_account_warming_sessions'.
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 usage when you have a specific session ID via the required parameter. It provides clear context but does not explicitly mention when not to use it or compare to alternatives (e.g., listing vs. getting a single session).
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, idempotentHint, and destructiveHint as safe. The description adds valuable context: only staff/CM-validated bans appear, not internal scans. It also describes the polling mechanism with the 'since' watermark. A slight deduction because the description does not explicitly state pagination or rate-limit implications beyond what the schema already covers.
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 reasonably concise at 5 sentences but provides substantial detail. It front-loads the core purpose and then adds lifecycle context, REST counterpart info, and polling guidance. Slightly verbose for an ideal tool definition but still efficient. Could tighten the enum examples or use a table, but overall well-structured.
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 no output schema and 7 parameters, the description covers lifecycle, polling, exclusions, and related webhook events. It explains the semantics of each status and resolution, ensuring the agent understands the data model. The parameter schema is fully described and the description compensates for the missing output schema by explaining what the tool returns (list of reports). Complete for a read-only polling tool.
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 schema already documents all parameters. The description adds value by explaining the purpose of the 'since' parameter as a polling watermark and the 'resolution' filter for staff decisions. However, it does not describe the 'include_screenshots' parameter's significance beyond the schema. Baseline 3 is met, and the extra lifecycle context justifies a 4.
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 for the caller's delivered accounts, covering the full lifecycle with specific statuses and resolutions. It distinguishes itself from sibling tools by focusing on bans and appeals rather than analytics, bundles, or account management.
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: as the REST counterpart to webhook events, and indicates it should be polled with the 'since' parameter. It also states what is excluded (detections from internal health scans never appear), helping the agent understand limitations without confusion.
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 show no hints (not readOnly, not idempotent, not destructive). The description discloses critical behaviors: that the response contains a secret not stored in the replay ledger, that idempotency keys are rejected, and the specific error code. This fully compensates for the lack of annotation hints.
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?
Four sentences with no redundancy. Each sentence adds essential information: purpose, warning, implication of warning, and consequences. Extremely efficient and front-loaded with the core action.
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 is complete for its purpose: creating an upload URL. It covers the operation and a key rejection scenario. There is no output schema, so it doesn't detail the response format (e.g., the upload URL structure), which is a minor gap given the complexity of a presigned URL flow.
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 nested body property. The description does not add any semantics about the parameters (filename, bundle_id, content_type) beyond what the schema already defines. Baseline 3 is appropriate as the schema fully documents the 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 explicitly states it creates a video upload URL and returns a presigned upload capability. It immediately clarifies it does not directly upload a video but initiates the upload process, clearly distinguishing it from sibling tools like tokportal_upload_video_direct.
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 warns against sending an Idempotency-Key header and specifies the error response if done. This is crucial guidance that prevents a specific failure mode, addressing a key operational constraint.
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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds valuable behavioral details beyond annotations: it reveals that each accepted task costs 1 credit, TokPortal locks and revalidates the account before debit, and all inserts commit in one transaction. It also explains partial-success semantics (rejected rows free). While informative, it could clarify the exact effect on credits for partial successes more precisely.
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, consisting of only five sentences with no redundancy. It is front-loaded with the core purpose ('Create comment tasks') and efficiently covers batch limits, credit costs, preconditions, transaction behavior, and idempotency recommendations.
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 (batch creation, credit charges, idempotency, preconditions) and the absence of an output schema, the description thoroughly covers what an agent needs: how to use it safely, what preconditions exist, what guarantees are provided, and how to avoid double charges. No gaps are apparent.
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 all parameters are described in the schema. The description adds no new parameter-specific details but does provide crucial operational context (e.g., idempotency usage) that isn't in the schema. The baseline is 3, but the extra context elevates it to 4.
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 'comment tasks', and specifies that it can handle single or batch (up to 200) operations. It effectively distinguishes from sibling tools like tokportal_list_comment_tasks, tokportal_delete_comment_task, and tokportal_get_comment_task by focusing on creation.
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 provides when to use the tool (creating comment tasks) and includes critical guidelines such as sending an Idempotency-Key for safe retries, reading credits_charged instead of calculating, and clarifying that rejected rows are never charged. It also describes prerequisites (saved account must be client-owned and allowed) and batch behavior.
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 indicate this is not read-only (readOnlyHint: false) and not idempotent, which is consistent with the mutation described. The description goes far beyond annotations by detailing atomic checks on credits, period end, and lock version before debiting, the handling of lapsed states even if recorded_status hasn't updated, and the preservation of video cadence. This level of detail completely compensates for the lack of comprehensive 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 at 3 sentences, front-loaded with the main action. However, the third sentence is somewhat dense and might benefit from slight restructuring for clarity, but overall it's efficient.
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 (nested object, 3 parameters, 100% schema coverage, no output schema), the description is complete. It explains preconditions (snapshot-based), behavior during/after billing period, atomic checks, and side effects on videos. Without an output schema, the description adequately conveys the outcome (reactivation with specific conditions).
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 fully documents the parameters. The description adds context about how the parameters (expected credits, period end, lock version) are used atomically but doesn't expand on the idempotency key or the id parameter. Still, the schema is rich enough (with descriptions) that the tool is well-understood without the description adding much per-parameter detail.
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 explicitly states it reactivates TokPortal Coverage from an explicit GET snapshot. It clearly specifies the verb 'Reactivate', the resource 'Coverage', and distinguishes it from sibling tools (no other tool mentions reactivation or coverage).
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 explains when to use this tool (reactivate Coverage), notes that reactivation is free while the billing period is already paid, and mentions when it accepts a lapsed state. The inclusion of atomicity checks and handling of scheduled videos provides clear context for appropriate usage without naming alternatives, but given the unique purpose among siblings, this suffices.
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 are minimal (non-read-only, not destructive, not idempotent), so the description carries the full behavioral burden. It credibly discloses that the operation debits 8 credits, is atomic (assignment, debit, task creation are tied together), creates a task in a manager's calendar, and handles completed bundles without delivery-age limit. It also states cancelled orders are never restored, which is critical behavioral info not captured by 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 dense but not verbose—six sentences covering purpose, prerequisites, process, and atomicity. Every sentence adds specific value (e.g., 'debits 8 credits', 'completed bundles remain eligible'), and the critical atomicity guarantee is front-loaded after explaining prerequisites. No extraneous content.
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 has three parameters (two required), no output schema, and moderate complexity (nested object, credit cost, manager routing), the description covers all essential aspects: prerequisites, credit cost, manager fallback logic, atomicity, and bundle eligibility rules. No return value is described, but the description implies the task appears in a calendar, so the outcome is clear. This is complete for the tool's complexity and schema richness.
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 parameter descriptions (e.g., id is a UUID saved account ID, body includes fields like requested_biography with platform-specific length notes). The description adds high-level context about the body being profile changes and id referencing delivered accounts, but the schema already does most of the work. One could argue the description doesn't tie the parameters to the atomic flow, but the schema is sufficiently rich.
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 requests profile edits for a delivered account, specifying the action (request profile edits), the resource (delivered account), and the scope (profile changes). It also distinguishes itself from siblings like tokportal_get_account_edit_request (which retrieves requests) and tokportal_configure_bundle_account (which configures account properties), making the 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit prerequisites: active TokPortal Coverage and a routable active account manager. It details the manager selection order (current active manager, still-active relationship, then eligible non-cancelled order history), which guides when the tool can be used. It also clarifies atomicity and that unavailable managers do not cost credits, implying safe retry conditions without explicitly stating alternatives. This is comprehensive guidance.
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, which already indicate idempotentHint=true and destructiveHint=true. It explains the atomic commit and refund mechanism, idempotency behavior, the distinction between current and historical task refunds, and the rationale for availability during paused Coverage. This is exemplary transparency for a credit-mutating 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?
The description is compact yet information-dense, with front-loaded purpose. Every sentence adds essential context—behavioral guarantees, credit refund details, availability edge case, and retry guidance. 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 the tool's simplicity (one required parameter, no output schema), the description is complete. It covers the action, constraints, behavioral nuances, idempotency, error handling advice, and edge cases. There is no missing information for a competent agent to invoke this tool correctly.
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 value by explaining the idempotency key reuse pattern beyond the schema's description, and reinforces the 'owned task' constraint. However, it does not detail the format or constraints of the 'id' parameter beyond the schema, which is fine given high 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 uses a specific verb ('Cancel') and resource ('pending comment task'), clearly distinguishing it from sibling tools like tokportal_create_comment_tasks, tokportal_get_comment_task, tokportal_approve_comment_task, and tokportal_dispute_comment_task. It explicitly states the action, the resource, and the required state ('pending').
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 cancels owned tasks only, only while status is pending, and remains available when Coverage is paused. It doesn't explicitly list alternatives, but the context implies this is the only cancellation tool among siblings, making the guidance clear.
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:

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

Score Badge

Copy to your README.md:

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

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/tokportal-python'

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