@scom82/topvisor-mcp

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation5/5
Each tool has a clearly distinct purpose covering project, region, searcher, keyword, and position management. There are no overlapping or ambiguous tools.
Naming Consistency5/5
All tools follow the consistent pattern 'topvisor_verb_noun' (e.g., add_project, check_positions, list_keywords). The naming convention is uniform and predictable.
Tool Count5/5
With 17 tools, the set covers the essential Topvisor API operations without being excessive. It provides a well-scoped surface for SEO position tracking tasks.
Completeness4/5
The tool set covers the core workflow (project setup, region/searcher management, keyword import, position checking and history). Minor gaps exist (lack of update/delete for projects and keywords), but these are mitigated by the generic request tool.
Average 3.7/5 across 17 of 17 tools scored. Lowest: 2.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 6 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only says 'Get', implying a read-only operation, but does not mention any side effects, authentication needs, rate limits, or pagination behavior. This is insufficient for a tool with 4 parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one short sentence) and front-loaded. However, it sacrifices completeness for brevity, leaving out essential details. It is adequately concise but not optimal.
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 4 parameters, no output schema, and no annotations, the description is incomplete. It fails to explain how to use parameters or what the response looks like, making it insufficient for confident use.
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 only 25% (only 'fields' has a description). The description does not explain parameters like 'orders', 'limit', or 'offset' beyond what the schema provides. It adds no additional value to 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?
Description clearly states the verb 'Get' and resource 'account transaction history' with specific transaction types (deposits, charges, bonuses). It distinguishes from siblings like 'topvisor_balance' and 'topvisor_get_history' by specifying the scope is transaction history, not just balance or generic history. However, it does not explicitly differentiate from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'topvisor_balance' or 'topvisor_get_history'. No conditions, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions the return type (snapshotsData per keyword) but lacks information about side effects, permissions, rate limits, or data freshness. The cross-reference to another tool is helpful but insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, each serving a purpose: purpose, context, and constraint. No wasted words, but it could be better organized with bullet points or clearer separation of parameter usage.
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 11 parameters, no output schema, and no annotations, the description is incomplete. It does not explain what snapshotsData contains, how filters work, or the meaning of type_range, count_dates, etc. More detail is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 55%, and the description repeats the constraint about date parameters already present in the schema. It adds no new meaning for other parameters like filters, type_range, or count_dates. The description fails to compensate for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves SERP snapshots for a project/region. It uses specific verbs and resources. However, it does not explicitly differentiate from sibling tools like topvisor_get_history or topvisor_get_summary, which might 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?
Provides a constraint about date parameters but no guidance on when to use this tool versus alternatives. No mention of when not to use it or prerequisites beyond the cross-reference to topvisor_check_positions.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions the tool 'Supports filtering, ordering, pagination,' which hints at functionality but does not disclose whether the operation is read-only, requires authentication, has rate limits, or any side effects. Critical behavioral traits are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences front-load the core purpose ('List keywords for a project') and then mention key features. Every word earns its place; no redundancy or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema, no annotations), the description is insufficient. It does not explain the required project_id parameter, the return format, pagination behavior, or any edge cases. The agent lacks essential context to use the tool effectively.
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 low description coverage (25%), and the description only generically mentions 'filtering, ordering, pagination' without detailing how parameters like filters, orders, limit, or offset work. It does not explain the meaning of specific parameters, their usage constraints, or default behavior, leaving the agent to guess from the schema structure alone.
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 action ('List keywords for a project') with a specific verb and resource. It mentions additional capabilities (filtering, ordering, pagination) but does not differentiate from sibling tools like topvisor_list_projects or topvisor_list_regions, which may have similar features. Hence, not a perfect 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?
The description provides no guidance on when to use this tool versus alternatives, such as topvisor_list_projects or topvisor_get_summary. It does not specify prerequisites, context, or exclusions, leaving the agent to infer usage from the tool's name and capability hints.
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?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the return type ('keywords[] with positionsData'), but fails to mention side effects, authentication needs, rate limits, or error behavior. With 15 parameters, much behavioral context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that convey purpose, a key constraint, and return type. No extraneous information, well front-loaded.
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 (15 parameters, no output schema, no annotations), the description is insufficient. It does not explain the meaning of 'position history', the structure of positionsData, or how optional parameters like competitors_ids or fields affect results. The description leaves the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 33%, and the description adds value by clarifying the mutual exclusivity of 'dates' vs 'date1+date2'. However, many parameters (e.g., fields, competitors_ids, type_range) are not explained in the description, leaving the agent with incomplete guidance.
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 retrieves position history for a project and regions, specifying the verb 'Get' and the resource 'position history'. However, among many sibling tools like topvisor_get_snapshots and topvisor_get_summary, it does not differentiate itself, missing an opportunity to clarify unique functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage constraint: 'Requires either dates array OR both date1 and date2.' This gives context on required parameters but lacks guidance on when to use this tool vs. alternatives (e.g., topvisor_get_snapshots), and no mention of when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It mentions return fields but does not disclose behavioral traits like handling of duplicates, error conditions, or idempotency. For a tool with 9 parameters, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loaded with the main purpose and return fields. However, it could be better structured by grouping related parameters or providing a usage example.
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 9 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on parameter interactions, error handling, and response structure beyond the returned fields. Not sufficient for an agent to reliably invoke the tool.
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 low (22%). The description adds meaning to group_name and keywords (e.g., including group_name in CSV headers), but most parameters like folder_id, move_duplicate, etc. remain unexplained. The description does not compensate for the schema gaps.
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 'import' and resource 'keywords into a project via CSV', and lists return fields. It distinguishes from siblings like list_keywords or add_project by focusing on CSV import.
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 condition for using group_name to assign keywords to groups, but does not explicitly state when to use this tool versus alternatives like topvisor_get_summary or topvisor_check_positions. Usage context is implied but not fully articulated.
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?
With no annotations, the description carries full burden but only mentions the add operation and prerequisite, omitting details on idempotency, error handling, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences, front-loaded with core action and a crucial usage hint, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple add tool, the description covers only basic purpose and prerequisite; it lacks details on return values, error conditions, or behavior, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only searcher_key has description); the tool description does not clarify project_id or add any meaning to the parameters beyond what the schema already 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?
Clearly states the verb 'Add' and the resource 'search engine (searcher)' to a project, distinguishing it from sibling tools like topvisor_add_region by noting the prerequisite ordering.
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?
Explicitly states that this tool must be used before adding regions, providing clear context for when to invoke it, though it does not detail alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It fails to disclose side effects, authentication needs, rate limits, or default behavior (e.g., pagination, default limit/offset). Only the effect of 'show_searchers_and_regions=1' is noted.
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, concise, and front-loaded with the core purpose. 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?
Given the lack of output schema and 7 parameters, the description is incomplete. It does not cover return format, pagination behavior (limit/offset), error handling, or how to interpret results. Basic completeness is achieved for listing but not for advanced usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (29%), but the description adds value by mentioning fields, filters, orders for precise queries and a specific example for show_searchers_and_regions. However, it does not explain syntax or behavior for all 7 parameters sufficiently.
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 'List all projects in the account' which specifies the action (list) and resource (projects) with scope (all). This distinctly separates it from sibling tools like add, balance, or other list 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 advises to 'Use fields, filters, orders for precise queries', which gives some guidance on how to refine results, but does not specify when to use this tool versus alternatives (e.g., topvisor_get_summary) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool returns (distribution across top positions, optional metrics) but does not mention potential side effects, error conditions, authentication requirements, or any limits. The behavior is adequately but not exhaustively described.
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 every phrase adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, no output schema, and no annotations, the description is somewhat incomplete. It covers the main idea but does not explain the return format, the role of optional parameters, or how the comparison works in detail. Adequate for a simple tool but leaves gaps for complex use.
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 only 22%, yet the description does not compensate by explaining the undocumented parameters (e.g., competitor_id, only_exists_first_date, show_* flags). It only mentions 'two dates' and the return metrics. The schema itself describes region_index and dates, but the description adds no extra meaning beyond that. Many parameters remain opaque.
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), the resource (positions summary), and the context (comparing two dates, for a project and single region). It also lists the specific return content (keyword distribution, optional dynamics, tops, averages, visibility metrics), distinguishing it from related tools like topvisor_get_history or topvisor_check_positions.
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 its usage for comparing two dates and retrieving summary metrics, which is enough to understand the basic intent. However, it provides no explicit guidance on when to use this tool over siblings, nor does it mention prerequisites or alternatives.
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?
No annotations are provided, so the description must carry the burden. It discloses return format ('dates array and seriesByProjectsId'), but does not explicitly state read-only behavior, side effects, authentication needs, or rate limits. It mentions 'single region' but omits the competitor_id parameter 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?
Two sentences, front-loaded with the main action and resource, immediately followed by return value description. No unnecessary words, 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 tool's complexity (11 parameters, no output schema), the description provides essential context: it returns chart data with dates and seriesByProjectsId. It does not detail nested structures or optional parameters, but it is sufficient for an agent to understand the tool's purpose and output. Slightly incomplete regarding competitor 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 description coverage is 45%, meaning some parameters are documented in the schema but many are not. The tool description adds general return context but no parameter-specific semantics beyond what the schema already provides. 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 chart data showing position distribution over time for a project and single region', using a specific verb and resource. It distinguishes from sibling tools like topvisor_get_summary (which provides summary data) by focusing on chart rendering with dates and seriesByProjectsId.
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 mention prerequisites, exclusions, or scenarios where other tools would be preferred. The description only explains what it does, not when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should fully disclose behavior. It only states it calls the API directly and passes the body verbatim, but lacks details on authentication, rate limits, error handling, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, the first states purpose and the second gives usage pattern. No redundant information, very 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 tool's generic nature, the description covers its main use case. However, since there is no output schema, it could mention that the response format varies by API method or provide a link to API docs. As is, it's 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?
The input schema has good coverage (75%) and descriptions for parameters. The description adds little beyond what the schema already provides, only summarizing the parameter roles (operator/service/method/path/body). Baseline 3 applies.
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's a generic escape hatch for calling any Topvisor API v2 method directly, distinguishing it from the many specific sibling tools by covering all methods including undocumented ones.
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 tells users to use operator/service/method path and pass body verbatim, and implies using this tool when no typed tool exists. However, it does not explicitly say to prefer typed tools when available.
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?
Discloses return shape uncertainty and raw result, but no info on side effects, authentication needs, or error conditions. No annotations to fall back on.
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 concise sentences, no wasted words, front-loaded with purpose.
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?
With no output schema, the description provides essential return value info and caveat. Sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions (100% coverage), but description adds no extra meaning beyond 'returns new project object'.
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+resource: 'Create a new project in Topvisor.' Distinct from sibling tools like list, check, import, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives; no mention of prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adds value by explaining the region_key vs region_index distinction. However, it does not disclose permissions, side effects, or error conditions, leaving room for more 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: first states purpose, second delivers critical post-add step and warning. No extraneous content, well 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 6 parameters and no output schema, the description covers the essential workflow context and a key gotcha. It could mention handling of existing regions or error responses, but is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema already documents most parameters. The tool description does not add new semantic detail for individual parameters 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?
Description clearly states the verb 'Add' and the resource 'region to a searcher for a project.' It distinguishes from sibling tools by referencing topvisor_list_regions and explaining the difference between region_key and region_index.
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?
Explicitly instructs to call topvisor_list_regions afterward to obtain region_index, and warns that region_key is not the same as region_index. Provides clear context for post-add behavior but does not include when-not-to-use or 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?
No annotations exist, so description carries full burden. It discloses the non-mutating nature ('preview... without actually running it') and the return format (pricesByUsers). Missing details like auth or rate limits, but acceptable for a simple cost check.
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: first states purpose, second gives usage guidance and return structure. No redundancy, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description is adequate but could benefit from more parameter guidance or example response. It references another tool for regions, which helps.
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?
Only 43% of parameters have schema descriptions, and the tool description adds little beyond schemas. It references regions_indexes as coming from topvisor_list_regions, but no extra semantics for other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it previews cost without running the check, and distinguishes from sibling topvisor_check_positions by saying 'use this before'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells when to use (before topvisor_check_positions to estimate cost). It does not list when not to use or alternative cost tools, but the context 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?
No annotations exist, so the description must fully disclose behavior. It notes the tool works without credentials, which is helpful, but does not explain data freshness, idempotency, or any rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first lists scope, second adds credential requirement. No redundant information.
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 parameters, no output schema, and no annotations, the description is fairly complete. It states what is listed and that no credentials are needed. However, it could hint at the output format (e.g., array of strings) for 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?
No parameters exist; schema coverage is 100% trivially. The description adds meaning by clarifying the output contents (services, operators, methods, etc.), which is valuable context beyond the empty 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 explicitly states the tool lists multiple API components (services, operators, methods, etc.) and notes it works without credentials. This is specific and distinguishes it from other tools that perform actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like topvisor_request or topvisor_list_projects. The use case is implied for discovery but not 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?
No annotations are provided, so the description carries the full burden. It explicitly labels the tool as 'ASYNC,' explains that it returns projectIds immediately while data collection runs in the background (minutes to hours), and describes how to monitor progress and retrieve results. It also notes parameter interactions (e.g., keyword_id overrides other parameters). This fully discloses behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences), front-loaded with the key fact 'ASYNC: Submit a position check job...', and efficiently structures the workflow: action, immediate result, monitoring, results retrieval, and cost preview. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers the expected behavior: it explains the async nature, the return of projectIds, the background processing timeline, and provides links to monitor (topvisor_list_projects) and retrieve results (topvisor_get_history). It also mentions cost preview (topvisor_check_price). For a submission tool, this is complete and self-contained.
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 57%, and the description adds contextual value for the `keyword_id` parameter (explains overriding behavior). However, the description does not elaborate on the `folders_ids`, `folders_ids_depth`, or `groups_ids` parameters, leaving their semantics partially unclear. The description compensates somewhat by describing the overall async workflow, but not fully for 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 clearly states the tool's purpose: 'Submit a position check job to the Topvisor queue.' It specifies the async nature, immediate return of projectIds, and distinguishes from siblings by linking to monitoring and results tools. The verb 'submit' and resource 'position check job' are specific, and the description helps differentiate from tools like topvisor_check_price and topvisor_get_history.
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 (to submit a position check) and what to do next: poll topvisor_list_projects for status, read results via topvisor_get_history, and preview cost via topvisor_check_price. It effectively outlines the workflow and alternatives, aiding correct 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?
With no annotations, the description fully discloses the computational nature of the balance (sum of deposits minus charges), the API limitation, and the custom implementation. Returns structured output with computed_balance, transaction_count, and last_transactions.
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?
Well-structured with purpose first, then technical detail. Slightly lengthy but all information is relevant and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully describes the return values (computed_balance, transaction_count, last_transactions) in the absence of an output schema. Covers API limitation and workaround, making it complete for a zero-parameter 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?
No parameters exist, so schema coverage is 100%. The description adds value by explaining the return object structure and the workaround logic, which goes 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?
Clearly states 'Get account balance' and specifies it computes from transaction history as a workaround for an API limitation. Distinguishes from sibling tools by explaining the alternative approach.
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?
Explicitly mentions when to use (getting balance) and describes the API limitation (bank_2/info endpoint empty for single-user accounts) and the workaround, providing context for alternative 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?
Despite no annotations, the description details the underlying API endpoint (get/projects_2/projects with show_searchers_and_regions=2), the mapping from region_key to region_index, and warns against confusing the two. It fully discloses the tool's behavior and common pitfalls.
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 well-structured: purpose first, then critical usage warning, an example, and a note about the API endpoint. Every sentence earns its place without unnecessary fluff, making it easy to parse.
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 parameter, no output schema, no annotations), the description fully explains the output (region_key and region_index), their significance, and provides an example mapping. It is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the single parameter (project_id) with a description, baseline 3. The description adds value by explaining the context to use the parameter (after adding regions) and the importance of the returned values, moving the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'configured searchers and regions', and the context 'for a project'. It specifies the return fields (region_key and region_index), and is distinct from sibling tools like topvisor_add_region or topvisor_check_positions.
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?
It explicitly says 'Always call this tool after adding regions to get the correct region_index values' and explains the critical distinction between region_key and region_index with an example mapping. This provides strong when-to-use guidance.
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:

[![topvisor-mcp MCP server](https://glama.ai/mcp/servers/SCom-82/topvisor-mcp/badges/card.svg)](https://glama.ai/mcp/servers/SCom-82/topvisor-mcp)

Score Badge

Copy to your README.md:

[![topvisor-mcp MCP server](https://glama.ai/mcp/servers/SCom-82/topvisor-mcp/badges/score.svg)](https://glama.ai/mcp/servers/SCom-82/topvisor-mcp)

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/SCom-82/topvisor-mcp'

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