Bisibility

Server Quality Checklist

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

Latest release: v0.6.1
Disambiguation3/5
Most tools are clearly distinct, but there are several overlapping pairs that create selection risk: list_api_keys vs list_project_api_keys, create_api_key vs create_project_api_key, and list_saved_keywords vs list_keywords vs list_ranked_keyword_suggestions. The saved-view/saved-keyword vs keyword concepts also blur boundaries since create_saved_view appears to be a keyword view while create_saved_keywords is a separate idea-saving concept.
Naming Consistency4/5
The naming predominantly follows a consistent verb_noun pattern (list_*, create_*, update_*, delete_*, get_*, set_*, enable_*, disable_*), which is good. However, there are notable inconsistencies: create_saved_view vs create_saved_keywords (singular vs plural for the same 'saved' concept), and get_* vs list_* sometimes overlap semantically (get_keyword vs list_keywords is fine, but get_cloud_import_compatibility, get_health, get_capabilities, get_me, get_provider_rates are mixed non-CRUD reads).
Tool Count3/5
At 87 tools this is far beyond the typical well-scoped range. The server spans many domains - projects, keywords, rank checks, alerts, webhooks, team management, providers, analytics, signals, migration - which warrants many tools, but 87 is heavy and will be hard for an agent to navigate. It lands in the 'too many (25+)' band, though the breadth of the product partially justifies it.
Completeness4/5
The coverage is impressively thorough across the domain: keywords have full CRUD plus bulk operations, providers have connect/test/settings/priority/enabled coverage, alerts have create/update/delete/list. Minor gaps include ownership transfer being UI-only, and no update/delete for saved views beyond delete. Overall nearly every workflow has a matching tool with no obvious dead ends.
Average 3.6/5 across 87 of 87 tools scored. Lowest: 2.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 15 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 Apache 2.0.
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.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations confirm this is a non-read, non-destructive mutation (readOnlyHint=false, destructiveHint=false), so the description carries the burden. It does not state whether channels default to something, whether idempotency_key guarantees deduplication behavior, whether unmapped conditions silently ignore irrelevant parameters, or what the response contains. For a create operation with no output schema, this is thin 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is concise, but it is under-specified rather than efficiently specified. It provides a topical overview without the operational detail needed for a tool with 16 parameters and 10 condition enums. Conciseness is earned by packing the right info tightly, not by brevity alone.
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 (16 params, 10 condition_type enums, condition-specific parameter couplings) and low schema coverage (25%), the description should map conditions to their relevant optional parameters and explain cross-field dependencies. It does none of this. The absence of this mapping makes the tool hard to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (most params are undocumented), and the description mentions only the four trigger categories. It does not explain which parameters apply to which condition_type (e.g., change_pct applies to change_pct condition, drop_positions to position_drop, competitor_domain to competitor_overtake, serp_feature to serp_feature), which is the essential semantic mapping for correctly invoking this tool. The description adds no parameter-level guidance beyond naming the trigger types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource ('Create an alert rule') and enumerates the specific trigger categories: project rank changes, thresholds, SERP features, or competitors. This distinguishes it from sibling tools like create_webhook and create_signal. However, it doesn't name alternative events or clarify that these categories map to specific condition_type enum values.
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 vs update_alert_rule, list_alert_rules, or delete_alert_rule. The description doesn't specify prerequisites such as needing a valid project_id or recipient_ids configuration, nor does it clarify how condition_type interacts with the optional parameters. With 16 parameters and many sibling alert tools, the lack of selection context is a notable gap.
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 and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond a basic listing statement—no mention of pagination behavior (despite a cursor parameter), ordering, or what fields are returned. For a list operation with existing annotations, this is thin but does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence—appropriately concise for such a simple tool. However, it leaves out critical usage details that this brevity could have accommodated, making the conciseness feel more like under-specification than earned 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?
With 3 parameters (including pagination cursor/limit), no output schema, and 33% schema coverage, the description is notably incomplete. It doesn't explain pagination semantics, response structure, or membership roles. The project_id param is well documented in the schema, but the cursor/limit pagination mechanism is completely unexplained. For a paginated tool this is a meaningful 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 only 33%; only project_id has a description. The description itself names no parameters. The cursor and limit parameters for pagination receive zero explanation in either the schema or description—the agent must infer how to paginate through results. This in an area where the description should have compensated.
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 tool name and title are clear ('list team members'), and the description states the purpose simply. However, it doesn't distinguish from sibling tools like list_team_invites or update_team_member_role, and it doesn't clarify scope (e.g., all members vs. active members). It's minimally adequate but not differentiating among the many team-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like list_team_invites, update_team_member_role, or remove_team_member. No mention of what a 'team member' includes or excludes relative to pending invites. The description provides zero context for selection among the several team-related 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 declare readOnlyHint=false, which correctly signals this is a write operation, and the description confirms it with 'Requires a personal access token with write scope.' However, the description doesn't disclose what happens on successful creation (returned project ID?), whether projects are immediately active, or whether the domain must be verified. With minimal annotation coverage (no openWorldHint or destructiveHint context), the description carries moderate burden but only covers the auth angle.
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 wording. The description is appropriately brief and the key behavioral caveat (write-scope token) is front-loaded with the core action. It earns its place without fluff.
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 creation/mutation tool with no output schema and only 50% parameter coverage, the description is underdeveloped. It doesn't state what a successful creation returns, how to reference the new project afterward, why idempotency_key matters, or what domain validation/tracking entails. Among 100+ siblings, the description provides insufficient context for an agent to correctly create a project and use the result.
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 50% — name and domain have descriptions, but tracking_scope and idempotency_key have NO descriptions. The description adds nothing about these undocumented parameters. tracking_scope's enum (city/country) leaves the agent guessing what it filters. idempotency_key is a critical semantic concept (deduplication) that the description doesn't explain at all, and the description doesn't compensate for this gap.
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 'Create a project' which identifies the action and resource, but it doesn't specify what creating a project entails or how it differs from similar creation tools among siblings (create_saved_view, create_signal, create_webhook, etc.). The verb+resource is clear but the scope and nature of a 'project' (a core entity with domain tracking) isn't elaborated.
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 or what prerequisites/context are needed beyond the auth note. The description doesn't mention that this is typically a foundational setup step, when to use tracking_scope, or contrast with update_project/delete_project for lifecycle management. It only mentions the auth requirement, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint=true, destructiveHint=false) already declare this is a safe read operation, so the bar is lower. The description adds little behavioral context — it doesn't mention pagination behavior, ordering, whether triggered alerts are time-bounded, or what 'triggered' means in terms of state. Annotations cover the safety profile, so 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?
A single short sentence — highly concise with no filler. However, it is arguably under-specified rather than genuinely well-structured, since so little useful guidance is packed into that sentence. Still, for what it attempts, there is zero waste.
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 there is 3 params, low schema coverage (33%), and no output schema, the description is too thin. It doesn't address pagination semantics between the cursor and limit parameters, doesn't describe the returned alert structure, and doesn't clarify filtering or ordering. For a list-type tool, this falls short of providing the agent enough to use it 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?
Schema description coverage is only 33% — only project_id has a description, while limit and cursor have no description. The tool description adds zero parameter guidance whatsoever. With low schema coverage and an absent output schema, the description should compensate but does not, providing no meaning for limit (max 200) or cursor pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'List triggered alerts for a project,' which states a clear verb+resource (list alerts) and scoping (for a project). However, it does not clarify what 'triggered' means distinct from alert rules or other alert-related tools like list_alert_rules, mute_triggered_alert, or mark_project_alerts_read, so differentiation among siblings is weak.
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 list_alert_rules (which likely lists alert rules rather than fired alerts) or when pagination via cursor vs limit should be used. The description does not mention any alternatives, prerequisites, or contextual usage cues, leaving the agent to 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 and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the scope (per project) and content (competitors, market data, suggestions). However, it doesn't disclose pagination behavior (cursor/limit semantics), whether all results are returned by default, or the shape/format of the returned data, which would be useful for a list tool with no output schema to clarify.
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 packs the core purpose efficiently. It's front-loaded with the primary action and scope. It could arguably be split or expanded with usage guidance, but as written it is economical 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?
This is a paginated list tool (limit, cursor) with no output schema, yet the description provides no information about pagination semantics, default result count, ordering, or what 'market data and suggestions' concretely means. For a list tool with two undocumented parameters and no output schema, the description is thinner than it should be to reliably guide an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, so the description should help clarify the undocumented parameters (limit, cursor). The description does not explain limit or cursor semantics at all, relying entirely on the schema's type/min/max constraints (which offer no semantic meaning). The project_id parameter is well documented in the schema itself. Given the moderate coverage gap and lack of param explanation, the description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List tracked competitors, market data, and suggestions for a project' clearly states the verb+resource (list competitors) and scopes to a project. However, it doesn't distinguish from the closely related sibling tools add_competitor/remove_competitor, though the list-vs-mutate distinction is somewhat implicit. The mention of 'market data and suggestions' adds some scope clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to use this tool vs alternatives. It doesn't note that competitors are per-project, doesn't mention pagination behavior with the cursor/limit params, and offers no exclusions. There are related tools like analyze_backlinks and list_ranked_keyword_suggestions that could overlap conceptually with 'market data and suggestions,' but no differentiation is provided.
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 provide safety guidance, so the description carries the burden. It does disclose the paid nature, ~$0.02 cost per page, 12-hour caching shared with UI/API, and the already_tracked marker semantics. However, it doesn't disclose readOnlyHint/destructiveHint behavior, rate limits beyond size, or pagination behavior (though offset*100 implies it). The cost/caching details are genuinely useful additions beyond 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, tightly written, each adds value: cost disclosure, caching behavior, and output field semantics. No wasted words. Could be slightly front-loaded toward the core action, but overall 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 read-ish list tool with 5 params, no output schema, and no behavioral annotations, the description gives cost, caching, and one output field but omits pagination behavior, what exactly a 'ranked keyword suggestion' contains, and how fresh/limit/offset interact. It's usable but leaves the agent to infer several operational details.
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 40%, leaving limit, offset, and fresh undocumented in the schema. The description implies one output field (already_tracked) and hints at caching behavior tied to 'fresh'. However, it doesn't explain limit/offset semantics or the fresh parameter explicitly. It compensates partially but not fully for the coverage gap.
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 it lists ranked keyword suggestions from a paid DataForSEO provider. However, it emphasizes cost/caching details more than the core function's scope, and doesn't clearly differentiate from siblings like list_keywords or research_keywords. The primary action is implied via the name and caching discussion rather than explicitly stated.
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 discloses that it's a paid provider lookup with caching, hinting at cost considerations. However, it doesn't explicitly state when to prefer this over alternatives like research_keywords, list_keywords, or add_keywords, nor does it state when NOT to use it. The cost warning is useful but doesn't substitute for explicit usage guidance.
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 destructiveHint=true, but the description adds nothing beyond the one-line action statement. It doesn't explain irreversibility, whether related data (saved views, alerts, signals) is affected by removal, or whether idempotent re-calls fail. For a destructive tool the description should expand on consequences; it doesn't.
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?
One terse sentence that states purpose without filler. Efficient and front-loaded. 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 destructive mutation tool with no output schema and minimal annotations, this is under-specified. It doesn't clarify what happens to associated tracked data, whether the operation is idempotent, or what error conditions apply (e.g., removing a nonexistent competitor). The incomplete idempotency_key documentation also reduces 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 coverage is 67%: project_id and competitor_id have descriptions, but the optional idempotency_key has none. The description adds no semantics beyond the schema. Baseline 3 is reasonable since the two required params are documented; the idempotency_key remains undocumented.
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 ('Remove') and resource ('a tracked competitor'), with scope ('from a project'). It distinguishes from siblings like add_competitor and list_competitors, though it doesn't explicitly mention those alternatives. It's clear but not maximally 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?
No guidance on when to use this tool versus alternatives, no prerequisites mentioned (e.g., competitor must exist, project must exist), and no effects described (e.g., whether this permanently deletes the competitor or just removes tracking). With destructiveHint=true and no explanation, an agent has no context on consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description lists the mutable settings (enabled, priority, primary) which adds some value. However, it doesn't disclose whether updates are transactional, whether setting one field affects another (e.g., does setting primary affect enabled?), or whether partial updates are supported. The description is reasonably neutral and doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, none wasted. Says exactly what to expect with the 'such as' enumeration. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a moderate-complexity update tool with 6 parameters and no output schema. The description covers the three main settings but doesn't address idempotency_key semantics, update behavior (partial vs full replace), or field interaction rules. Given the many sibling tools that overlap in purpose and the lack of annotations clarifying mutation semantics, this 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 coverage is low at 33%, covering only project_id and provider_id. The description mentions 'enabled state, priority, or primary status' which maps to the enabled, priority, and primary parameters, adding some meaning. However, it doesn't explain the idempotency_key parameter at all, and doesn't clarify semantics like whether priority is 0=highest, whether primary=true implies enabled, or interaction between the three optional fields. The description partially compensates for the low schema coverage but leaves gaps.
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 'Update provider settings such as enabled state, priority, or primary status' which clearly identifies the verb (update) and resource (provider settings). However, it doesn't distinguish from the many sibling tools like set_provider_enabled, set_provider_priority, set_primary_provider, which appear to do overlapping single-purpose updates. The description gives no sense of scope difference from those 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 generic update tool versus the more specific siblings (set_provider_enabled, set_provider_priority, set_primary_provider). Given the large sibling list with similarly-named provider tools, this is a significant gap. No when-to-use or when-not-to-use guidance is provided.
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 safety profile is clear from structured data. The description adds minimal behavioral context beyond a marginally confusing 'public bisibility' scope note (typo aside). It doesn't describe output format or pagination, but for a capabilities-list tool that's a modest gap given annotations are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence is appropriately concise, but the typo ('bisibility') and slightly awkward phrasing ('exposed for agent workflows') reduce clarity. The sentence earns its place but could be tightened and corrected.
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 zero-parameter read-only discovery tool with strong annotations, the description is adequately complete. However, it doesn't specify what the returned list actually contains (endpoint names? permission scopes? capability identifiers?), which an agent might need to know before relying on the response. Given no output schema exists, the description carries some burden to describe return expectations.
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 the schema coverage is 100% (empty properties object). With 0 parameters, the baseline is 4 per the rubric. There's nothing for the description to add about parameter semantics, so this default applies appropriately.
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 the public bisibility API capabilities exposed for agent workflows' with a clear verb+resource, but contains a typo ('bisibility' instead of presumably 'visibility'). The purpose is largely inferable from the name and title, making it somewhat redundant, though it does add the useful scoping note about 'agent workflows'.
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. While the sibling set includes get_health (a similar discovery/meta endpoint), the description does not differentiate or discourage misuse. Context is not elaborated beyond the bare listing action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, which already indicate a non-read, non-destructive mutation. The description adds little beyond 'Add' implying a mutation. It doesn't note idempotency behavior, duplicate handling, or label uniqueness despite having an idempotency_key parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence, zero waste. Front-loaded with the core action. Could arguably add a bit more given the two undocumented params, but for its length it's efficiently written.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations describing side effects, no output schema, and 50% param coverage, the description is thin. It doesn't address duplication behavior despite an idempotency_key, what response is returned, or how it relates to list_competitors/remove_competitor workflow. Sibling tools suggest a competitor workflow the description fails to contextualize.
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 50% — the domain and project_id parameters have descriptions while label and idempotency_key do not (2 of 4 undocumented). The description mentions 'tracked competitor domain' and 'project' but adds no meaning beyond schema. With partial coverage, the description could compensate for the undocumented label and idempotency_key but doesn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a tracked competitor domain to a project' uses a specific verb (Add) plus resource (competitor domain) and scoping (to a project). It clearly distinguishes from siblings like list_competitors and remove_competitor.
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 when-to-use guidance is provided. With siblings list_competitors and remove_competitor, there is no guidance on when adding vs removing/list is appropriate, nor whether a project must exist first or if there are limits on competitor count per project.
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 give readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds the key behavioral fact that 'Keywords already tracked or saved are skipped' (idempotent skip behavior). However, with no output schema and openWorldHint=false, it doesn't clarify return semantics or confirm whether skipped keywords produce errors or partial success responses.
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, front-loaded with the core purpose and the key caveat. No wasted words, though the difference between keywords-as-strings vs keywords-as-objects is only implied by the schema, not the 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 create operation with openWorldHint=false, destructiveHint=false and no output schema, the description is reasonably complete. But given the skip behavior and the nested object/string dual format in the keywords array, it could clarify the valid string-vs-object trade-offs and the return shape when keywords are skipped. The sibling 'add_keywords' and 'delete_saved_keyword' relationships are not clarified.
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 67% with 3 parameters. The keywords array and project_id already have detailed schema descriptions, and idempotency_key is a familiar concept. The description adds minimal value since the schema already documents the parameters well; the skip behavior is the only genuinely useful addition beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Save keyword ideas without starting paid rank tracking' which clearly states the verb (save) and resource (keyword ideas) and the key distinguishing behavior (not starting rank tracking). However, it doesn't differentiate from the sibling tools 'add_keywords' or 'list_saved_keywords' explicitly, so it relies on the tool name to imply the saved-keywords workflow distinction.
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 conveys usage context ('without starting paid rank tracking') which distinguishes it from add_keywords. However, there's no explicit when-to-use vs alternative guidance, and 'Keywords already tracked or saved are skipped' provides a behavioral note rather than 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 declare readOnlyHint=true and destructiveHint=false, so the agent already knows this is a safe read operation. The description adds no behavioral context beyond the annotation coverage—it does not disclose result size limits, pagination behavior (cursor-based), or how filters combine. With read-only annotations carrying the safety profile, the description's marginal added value earns a baseline 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 a single efficient sentence that front-loads the primary action ('List keywords for a project') and summarizes capabilities in a compact list. There is no wasted prose. It could arguably add a bit more value per sentence, but as written it is appropriately lean.
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?
This is a complex tool with 12 parameters, most undocumented in the schema (17% coverage), no output schema, and no explicit pagination or filtering semantics in the description. For a tool of this complexity, the single-sentence description is materially inadequate. It doesn't explain the cursor-based pagination model, how search/filters combine, what ordering defaults apply, or any rate limits.
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 very low at 17%, meaning the description must compensate for poorly documented parameters. However, the description only lists feature categories (pagination, search, filters, sorting) without mapping them to specific parameters like cursor, position_gt/lt, intent, topic, or device. Only project_id has a schema-level description. The description adds some semantic grouping but doesn't bridge the coverage gap meaningfully, warranting a 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 verb+resource ('List keywords for a project') and enumerates supporting capabilities (pagination, search, filters, sorting). It distinguishes it from sibling read tools like get_keyword (singular retrieval) and list_ranked_keyword_suggestions. However, it does not explicitly name sibling alternatives for differentiation, so it scores 4 rather than 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 lists features (pagination, search, filters, sorting) but provides no when-to-use guidance or exclusions. It does not clarify when one would choose this over list_ranked_keyword_suggestions, list_saved_keywords, or search_locations, nor does it mention key requirements like project_id being mandatory. Usage context is only implicit through listing capabilities.
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 destructiveHint=true and readOnlyHint=false, so the mutation is known. The description adds the 'current' option detail which reveals it can revoke the tool's own configured token, a meaningful behavioral consequence (the agent could lose access). It doesn't elaborate on reversal/immediate effect, but annotations carry the destructive burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One clean sentence with zero waste. States the action, the resource, the parameter semantics, and the special 'current' case efficiently. Excellent front-loading.
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 mutation tool with destructive annotations and no output schema, the core action is clear. However, given the 'current' special value that could revoke the agent's own configured token, more explanation of side effects (e.g., whether revocation is immediate, what errors occur) would help. With two params and one undocumented, it's adequate but not rich.
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 only 50%, and the description only clarifies the token_id parameter (by id or 'current'), which adds value. However, the idempotency_key parameter has no schema description and the tool description doesn't mention it at all, leaving it completely unexplained. The description partially compensates for one param but ignores the other.
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 (revoke), the resource (personal token), and by what means (by id or 'current'). It distinguishes itself from siblings like revoke_api_key and revoke_migration_token by specifying 'personal token' as the target, though it doesn't explicitly compare. Strong single-sentence 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 mentions the 'current' option which is useful usage context, but provides no guidance on when to use this tool vs alternatives (e.g., when to use list_personal_tokens first, or when to use revoke_api_key instead). No mention of consequences like auth impact or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the ability to 'clear' the target URL (implying null support), which adds some value. However, with no annotations describing behavior (readOnlyHint=false, destructiveHint=false are defaults), the description carries the burden of explaining mutation effects, idempotency, permissions, or whether clearing affects future rank checks. None of this is disclosed. It doesn't contradict annotations, but it's thin on behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with zero waste. The 'Set or clear' wording packs semantic content compactly. It could arguably be slightly more informative while staying concise, but it earns a solid score for front-loaded, economical writing.
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 focused single-purpose mutation tool with a clear schema and no output schema, the description is nearly adequate. However, it doesn't explain what 'evaluating a keyword ranking' means, whether this is a permanent overwrite, whether it triggers re-checks, or the expected behavior when clearing with subsequent rank checks. For a tool with no output schema and no annotations, slightly more context would be valuable.
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 75%: the schema documents keyword_id, project_id, and target_url but NOT idempotency_key. The description doesn't add parameter details beyond the schema, but with 75% coverage the baseline is near the high bar. The concept of 'clearing' (null target_url) maps to the 'Set or clear' phrasing, adding slight meaning beyond schema. A minor gap remains for idempotency_key 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 a clear verb+resource+scope: 'Set or clear the target URL used when evaluating a keyword ranking.' This clearly distinguishes it from sibling tools like update_keyword and add_keywords by specifying its focused purpose on the ranking target URL. It clearly conveys what action is taken and on what resource, though it doesn't explicitly name a differentiating sibling.
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 update_keyword or bulk_update_keywords. It implies usage context via the phrase 'when evaluating a keyword ranking' but offers no explicit when/when-not guidance or mention of alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, signaling a mutating non-destructive operation. The description adds no further behavioral context—such as whether disabling is reversible, what happens to associated data, or whether testing is needed. Given the annotation coverage is decent, a mid score is appropriate, but there's no value added 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?
Single sentence, zero waste, front-loaded with the action. However, given the tool's simplicity, this is appropriately concise without sacrificing needed context. Could add brief usage guidance but maintains 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?
No output schema, no annotations explaining side effects or reversibility, one undocumented parameter (idempotency_key), and no guidance on preconditions. For a state-changing tool in a provider-management cluster with many siblings, the description is too thin to fully guide 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 75% (3 of 4 params described). The enabled, project_id, and provider_id params have helpful schema descriptions. The idempotency_key has no description in either schema or tool description, leaving one param undocumented. The description adds no meaning beyond the schema, so baseline 3 is fair.
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 "Enable or disable a provider for a project" uses a clear verb+resource combination and states the two possible states. It's concise and clear, though it doesn't explicitly distinguish from sibling tools like connect_provider or update_provider_settings, which limits differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like connect_provider, update_provider_settings, or set_provider_priority. The description and schema don't explain when enabling/disabling is appropriate versus connecting a provider, or any prerequisites (e.g., provider must be connected first).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false. The description adds that 'Provider rate limits and connection authorization rules apply,' which supplements the openWorldHint by warning that this non-read operation may hit external rate limits and require authorized connections. However, it doesn't disclose what happens if the connection is unauthorized, whether sync is partial or full, or whether previously synced data gets replaced—costly gaps for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action. The first sentence states what the tool does and for what scope, and the second adds the key constraint (rate limits and authorization). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutating sync operation with no output schema, open-world implications, and an undocumented idempotency parameter. Given this complexity, the description is somewhat thin—it should clarify the idempotency_key semantics and what the sync actually returns or how to confirm success. But it does convey the essential scope and main caveats, making it minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, meaning only project_id has a description in the schema (the idempotency_key parameter has none). The description itself identifies the project as the scope ('project's own connected analytics accounts') and mentions rate limits, but it does not compensate for idempotency_key's missing documentation—not explaining its idempotency guarantee or how to use it to avoid duplicate syncs. Given the 50% coverage, the description should have explained the undocumented parameter.
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 ('Synchronize') and resource ('traffic snapshots from the project's own connected analytics accounts'), giving a moderately clear purpose. However, the exact mechanics—what 'synchronize' means here (pull fresh data? push data to accounts?) and how it differs from related traffic tools like list_traffic_snapshots or get_rank_check—aren't clarified, so sibling differentiation is weak.
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 ('Synchronize traffic snapshots from the project's own connected analytics accounts now') and notes provider rate limits and connection authorization rules apply, giving some context about when this should be invoked. However, it doesn't explicitly state when NOT to use it or name alternatives like list_traffic_snapshots (for reading existing snapshots) or test_provider_connection (for validating connectivity) when the goal is just inspection rather than a sync.
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 destructiveHint=true and readOnlyHint=false, so the description's mutation nature is covered. The description adds the 'Requires admin access' permission context, which adds value beyond annotations. No contradiction detected. However, it doesn't disclose what happens to the webhook's associated behavior (e.g., no further events sent, idempotency 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?
Two short sentences, no wasted words. Front-loaded with the action verb. Could arguably be more concise but the current length is appropriate for a deleting 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?
With destructiveHint annotation and a clear purpose, this is largely sufficient for a simple resource deletion. However, the idempotency_key parameter is completely unexplained, there's no mention of what happens post-deletion, and the admin access requirement is the only behavioral context. Adequate but with gaps for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: project_id and webhook_id are well-described in the schema ('list_projects returns valid project ids'), but idempotency_key is undocumented in both schema and description. The description adds no parameter-level meaning beyond the schema. Baseline 3 is appropriate given moderate 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 'Delete a webhook endpoint' with a specific verb and resource, clearly distinguishing it from siblings like create_webhook and update_webhook. However, it doesn't explicitly differentiate from other destructive operations beyond the verb-resource combination.
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 includes 'Requires admin access' which hints at a precondition, but provides no guidance on when to use this vs alternatives, no consequences of deletion, and no context about irreversible effects relative to other webhook operations. There's no 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, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds the 'active' filter (only active tokens are returned) which is useful and consistent with annotations. No mention of pagination behavior, which the cursor/limit params imply but is not disclosed.
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?
Single sentence, zero waste. Efficient and to the point. The term 'active' is the only substantive word beyond the basic resource+verb, but it adds meaningful scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with readOnlyHint and non-destructive annotations, this is adequate: reads are low-risk. However, with pagination parameters present (limit, cursor) and no output schema, the description could note that results are paginated/ordered. Given 3 params and simple semantics, this is reasonably complete but leaves pagination behavior implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only project_id has a description). The description mentions 'for a project' which maps to project_id, but adds nothing about limit or cursor (pagination). However, the meaning of list-style limit/cursor params is fairly standard and inferable from their names.
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?
Clear verb+resource: 'List active migration tokens for a project.' It specifies the action (list) and resource (migration tokens), and scopes to 'active' tokens and 'a project'. It distinguishes reasonably from sibling mint_migration_token and revoke_migration_token (those are create/delete verbs), though list_personal_tokens and list_api_keys are similarly-named siblings that lack explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus alternatives like list_personal_tokens or list_api_keys. The description merely states the action without context about when a migration token listing is appropriate, prerequisites beyond project_id, or scenarios where this tool is preferred.
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 notes 'The HMAC secret is write-only,' which is valuable behavioral context beyond annotations — it tells agents not to expect the secret back in responses. However, annotations already declare readOnlyHint=false (mutation is expected), and the description adds little else about what happens on creation, validation failures, or delivery behavior. The write-only secret note is the main added 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?
Two short sentences communicate the core purpose and the key behavioral caveat (write-only secret). No wasted words. Could arguably add more but for what it covers, it's tight and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with no output schema, the description is thin. It doesn't mention what response to expect (webhook id? confirmation?), how the created webhook appears in list_webhooks, what auth/permissions are required, or the meaning of the idempotency_key parameter which affects retry semantics. Given 6 parameters and no output schema, more context would help.
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 50%, meaning 3 parameters (enabled, description, idempotency_key) lack schema descriptions. The write-only HMAC note adds meaning beyond the schema's 'Secret you provide to sign webhook deliveries with HMAC,' clarifying the secret won't be retrievable later. However, the description doesn't explain the idempotency_key parameter, which is significant for a create operation.
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 it creates a webhook endpoint with specific verb+resource ('Create a webhook endpoint'). It clearly distinguishes from siblings like list_webhooks, update_webhook, and delete_webhook, which are separate operations on the same 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 versus alternatives. There's no mention of prerequisites like needing to list webhooks first, no mention that this is a create operation distinct from update/delete, and no context about when a webhook would be appropriate. The schema does show required params (project_id, url, hmac_secret) but the description gives no 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 and destructiveHint=false, so the safety profile is covered by structured data. The description adds that it checks SERP providers in addition to general API health, which is useful context. No contradictions with annotations. It doesn't disclose the return format or what specific health indicators are measured, but given annotation coverage, a 3 is reasonable.
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 waste. However, there is a minor typo ('bisibility' should be 'visibility'), which slightly detracts from quality. Otherwise, it's appropriately compact and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless health check tool with readOnlyHint and destructiveHint annotations, the description is mostly sufficient. It could benefit from noting what health information is returned (e.g., API status, per-provider availability) and whether any auth is required, but given the tool's simplicity and strong annotation coverage, it's adequate.
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 description coverage is 100% (no parameters to document). With 0 params, baseline is 4. The description reasonably clarifies what the tool checks (API health and SERP providers), which is the only semantic meaning needed for a parameterless tool.
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 uses a specific verb+resource ('Check visibility API health') that states the tool's core function, and mentions it also checks configured SERP providers. However, it's somewhat vague — 'health' is broad, and it doesn't detail what health information is returned (uptime, error rates, provider status?). It distinguishes from siblings reasonably since no other tool is titled for health checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a diagnostic/read tool by its name and title, and the readOnlyHint annotation reinforces safe read usage. However, no explicit guidance is given on when to use it versus alternatives (e.g., get_provider_rates, test_provider_connection, list_providers), nor are exclusions stated. There is no clear context about when a health check 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, so the safe-read profile is established. The description adds little beyond 'get one result by id' — it doesn't address pagination, result size, latency, or whether the result includes rank positions, dates, or competitor data. With annotations covering safety, a 3 is appropriate as the description adds minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero waste. Fully front-loaded with the purpose stated in the first four words. Nothing extraneous.
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?
This is a simple single-resource retrieval with good annotations and 100% schema coverage, so completeness is largely achieved through structured data. However, there is no output schema and the description doesn't mention what a rank check result contains (rank, date, keyword, URL, position history), which the agent may need to interpret the return value. Adequate but not rich.
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 check_id and project_id have pattern validation and descriptions in the schema. The description repeats 'check id' without adding semantic detail beyond what the schema already provides (e.g., that project_id must belong to a valid project, or whether check_id must be from the same project). Baseline 3 is correct when 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 'Get one rank check result by check id' states the verb (get), resource (rank check result), and identifies the primary identifier (check id). It's clear and specific, though it doesn't explicitly distinguish from siblings like run_rank_check, get_rank_history, or export_rank_history, which are related rank-check 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?
The description provides no guidance on when to use this tool versus alternatives. Given siblings like run_rank_check, get_rank_history, and export_rank_history, an agent could benefit from knowing that this retrieves a single result by ID while get_rank_history covers historical data and run_rank_check triggers new checks. No exclusions 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.
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 safety profile is well covered. The description adds the pagination and date-filter context. However, it doesn't describe pagination behavior (cursor handling, default limits) or whether results are chronological or newest-first, which would be useful. With annotations covering the safety profile, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero waste, front-loaded with the core purpose. All meaningful info is packed efficiently.
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 read-only list endpoint with pagination, the description is adequate but missing key details: date format for since/until, default response ordering, page size default, and how cursor pagination works. With no output schema, return structure is undocumented. The 7-parameter surface with 29% coverage needs more detail to be fully complete.
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 29% (only keyword_id and project_id have descriptions). The description mentions 'date, status, and pagination filters' which loosely maps to since/until/status/limit/cursor, but provides no format details for since/until (date format?) or meaning of cursor. With 5 of 7 parameters having zero documentation in both schema and description, this is a significant gap.
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?
Clear verb+resource: 'List historical rank checks for a keyword' with specific scope. It names the filters (date, status, pagination) which helps distinguish it from related tools like get_rank_check_result, list_keywords, and export_rank_history. However, it doesn't explicitly name sibling alternatives to differentiate.
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 what is listed (historical rank checks) and mentions filters, giving implied usage context. It doesn't explicitly note when to use this vs export_rank_history (which likely exports the same data) or get_rank_check_result (single result). No explicit exclusions or alternatives named.
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 safety profile is covered. The description adds the semantic nuance that these are per-project 'conditions' rather than fired events, which is useful. However, it doesn't disclose pagination behavior (though cursor/limit params suggest it) or the return shape.
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?
A single, well-phrased sentence that efficiently conveys scope and purpose with zero waste or redundancy. Appropriate for a straightforward list-style 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 list tool with good annotations (read-only, non-destructive), moderate completeness. It communicates the core purpose and project scoping. However, no output schema, no pagination explanation beyond the presence of cursor/limit params, and no guidance on what a 'rule' object looks like or how results are ordered.
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 33% with the project_id parameter well documented in-schema ('list_projects returns valid project ids'), so the schema partially carries the burden. The description adds the concept of 'per-project conditions' tying rules to a project context. However, limit and cursor lack any description beyond type constraints, and the description doesn't compensate for the 67% coverage gap.
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?
States a specific verb+resource ('list the per-project conditions that decide when a notification fires'), clearly identifying it as the read/listing tool for alert rules. It's distinguishable from siblings like create_alert_rule, update_alert_rule, list_triggered_alerts, and delete_alert_rule, though it doesn't explicitly contrast itself.
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 vs alternatives like list_triggered_alerts (which lists actual fired notifications vs the rule conditions). The description notes 'per-project conditions' implying it needs a project_id, but doesn't clarify special cases like pagination use or how it relates to the triggered-alerts counter tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false correctly indicating this is a mutation. The description discloses it creates (mints) a token, which aligns. However, it doesn't reveal what the minted token value looks like, whether idempotency_key makes the operation repeatable, or any rate/usage limits. DestructiveHint=false is consistent. Some value added but not a rich disclosure.
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?
A single concise sentence with zero waste. Front-loaded with the action and target. Appropriate length for the 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?
For a mint/create-style tool, the description lacks detail about what the minted token grants access to, how the scope parameter affects it, and what response format is returned (no output schema). Given sibling tools exist for listing and revoking, the description could clarify token semantics. Fields are mostly self-describing but behavioral outcomes are underspecified.
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 (33%: only project_id has a description). The description itself adds no parameter details. However, three parameters are inferable: project_id (target of minting), scope (enum full/keywords for token scope), idempotency_key (clearly self-describing). The description doesn't explicitly explain scope's meaning or the behavior of idempotency_key, leaving some gap but the schema does provide some 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?
Description states a specific verb+resource: 'Mint a migration token for a project.' It clearly identifies what the tool does and for what target. Among siblings, the related list_migration_tokens and revoke_migration_token provide context, and this tool's 'mint' action is distinct from those, giving some differentiation though not explicitly named.
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. Siblings list_migration_tokens and revoke_migration_token exist but the description doesn't distinguish when to mint vs list vs revoke, nor any prerequisites (e.g., need a project, need prior token). Context is implied by the action but no explicit when/when-not guidance is provided.
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 destructiveHint=true annotation already flags this as a destructive operation, so the description carries a lighter burden. The description is straightforward and consistent with annotations - 'Revoke' clearly implies the token becomes invalid. No additional behavioral detail (e.g., whether revocation is permanent, or affects existing operations) is disclosed, but the annotation covers the core risk profile.
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?
A single precise sentence that fully captures the operation without any waste. Front-loaded with the action verb and target resource. Nothing extraneous.
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 operation on a single resource with no output schema, the description is adequate but thin. The sibling tools 'mint_migration_token' and 'list_migration_tokens' provide context for the token lifecycle, but the description doesn't connect to them or explain the idempotency_key parameter (which lacks schema documentation). Given the write/destructive nature, slightly more context about the effect 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 67% - both required parameters (project_id, token_id) have schema descriptions. The description adds no additional semantic meaning beyond what the schema provides. The idempotency_key parameter has no schema description and the tool description doesn't mention it either, leaving a gap, but overall the schema carries most of the burden.
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 'Revoke a project migration token' uses a specific verb ('Revoke') and resource ('migration token'), clearly distinguishing it from related sibling tools like 'mint_migration_token' and 'list_migration_tokens'. It's clear and concise though it doesn't elaborate on the object's nature.
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 like revoke_api_key, revoke_personal_token, or revoke_team_invite, though the token type differs. The destructiveHint annotation signals caution, but no explicit context on when revocation is appropriate or consequences is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating, destructive operation. The description adds the 'pending' scoping constraint, clarifying only pending invites can be revoked. However, it doesn't disclose whether the action is reversible, whether permissions are required, or what happens to the invitee relationship. Given the annotation coverage, this is adequate but not deeply transparent.
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?
A single concise sentence that states the verb, resource, and state (pending). Zero wasted words, appropriately short for a straightforward revocation 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 destructive mutation tool (destructiveHint=true) with 3 params and no output schema, the description is minimal. The 'pending' qualifier and state constraint are useful, but it doesn't disclose edge cases (e.g., what happens if invite already accepted or expired), permissions needed, or side effects. The annotation flags destructiveness, which helps, but for a tool with potentially irreversible effects, more behavioral context would benefit 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 description coverage is 67%, and the schema already documents invite_id and project_id with their patterns and descriptions. The third parameter, idempotency_key, has no description in the schema and the tool description doesn't explain it either—the agent would have to guess its purpose. The description adds no parameter-level semantics beyond the schema. With partial coverage, the description doesn't compensate for the undocumented idempotency_key.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Revoke a pending project team invite' uses a specific verb (revoke) and resource (pending project team invite), clearly distinguishing it from sibling tools like create_team_invite, resend_team_invite, and list_team_invites. It could be more specific about scope, but the verb+resource pairing is clear and 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 provides no guidance on when to use this tool versus alternatives such as resend_team_invite, remove_team_member, or how it differs from deleting an active membership. It states it operates on 'pending' invites, which implies the target must be in a pending state, but there are no explicit preconditions, no mention of when not to use it, and no exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=false and destructiveHint=false, so the mutation nature is disclosed. The description adds the interpretation detail that 'lower numbers are preferred first,' which is genuinely useful behavioral context. However, it doesn't disclose idempotency behavior, or describe what happens when priority ties or conflicts occur among providers.
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 short sentences, zero waste. Every word adds value. The directionality clue is packed efficiently into a single sentence.
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 4-param mutation tool without output schema or enums, the description is nearly sufficient. Gaps remain: no statement about whether this overwrites existing priority or appends to a list, no idempotency semantics, and no note about valid priority ranges beyond what schema constraints already provide.
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 75% (3 of 4 parameters have descriptions). Priority, project_id, and provider_id are all documented in-schema. The description adds the ordinal-interpretation hint for priority ('lower numbers preferred first') which enriches meaning. However, idempotency_key is undocumented and the description doesn't compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-resource-action: 'Set provider priority for a project' with the important scoping clue 'Lower numbers are preferred first.' The purpose is unambiguous, though it doesn't explicitly differentiate from sibling tools like set_provider_enabled or set_primary_provider, which could be confused with priority setting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use hints, no context on alternatives, and no relationship to sibling tools like set_primary_provider or set_provider_enabled. An agent choosing between these provider-related setters would receive no guidance on which to invoke, aside from the inferred meaning of 'priority.'
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 destructiveHint=true and readOnlyHint=false, so the mutation nature is established. The description adds the scope (applies to every supplied keyword id) but doesn't disclose side effects like whether delete is permanent, whether partial failures occur, or rate limits on 500-keyword batches. With destructiveHint already set, the description adds modest 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?
Single sentence, front-loaded with the operative verb, and lists operations efficiently. No wasted words, though it could arguably add one sentence on per-operation parameter requirements without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters with a nested 'schedule' object and no output schema, and the description covers only the operation dimension. It doesn't clarify which parameters apply to which operations (e.g., set_frequency uses frequency or schedule?), nor disclose behavior when incompatible params are passed alongside an operation. For a multi-mode mutate tool, more behavioral specification is warranted.
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 63%, so the schema documents most parameters including operation enum values, frequency enum, target_url, and idempotency_key format. The description adds mild value by naming the operation types in prose, but the description-to-operation mapping isn't explicit (e.g., no statement that 'add_tags' requires the tags param). The 37% uncovered schema surface (schedule nested object, jitter_minutes) isn't compensated by description detail.
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 uses a specific verb+resource ('Bulk mutate keywords') and enumerates the exact operation types (adding tags, removing tags, setting frequency, setting target URL, deleting). It distinguishes from siblings like update_keyword (single) and set_keyword_target_url, though it doesn't explicitly name a distractor sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'Bulk' implies this is for many keywords at once versus single-keyword siblings, providing implicit usage context. However, no explicit guidance is given about when to use this vs set_keyword_target_url or update_keyword, nor any mention of required project_id context or alternative tools for single-keyword operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description explains that this tool both creates AND updates credentials, which is useful. However, with 10 parameters and no output schema, the description doesn't disclose what happens on update vs. connect (e.g., whether existing credentials are overwritten, whether test is performed), leaving significant behavioral ambiguity for a state-changing 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 three sentences and front-loads the core purpose first. It packs provider categorization and self-hosted endpoint info efficiently. No wasted words, though the group of related fields (enabled/primary/priority/cost_per_check) could have been briefly referenced.
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 complex tool with 10 params, nested objects, no output schema, and low schema coverage, the description provides essential context (provider categories, endpoint explanation) but omits important behavioral details: idempotency semantics, overlapping top-level vs. nested credentials, effect of enabled/primary/priority flags, and whether this triggers a live connection test. It's adequate but leaves notable gaps for a state-changing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, so the description carries a burden. It adds value by explaining the endpoint field's purpose (base URL for self-hosted providers) and enumerating valid provider_id values. However, it doesn't clarify the relationship between top-level login/secret vs. nested credentials.login/secret, nor the semantics of enabled, primary, priority, cost_per_check, or idempotency_key — a meaningful gap given 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?
Purpose is clear: 'Connect or update credentials for a project provider.' The verb 'connect/update' plus resource 'project provider' is specific. It distinguishes itself from siblings like disconnect_provider, test_provider_connection, set_provider_enabled, and set_provider_priority by focusing on credential setup/update, though it doesn't explicitly name these alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context about which provider IDs are valid for each category (SERP: dataforseo/serpapi; analytics: ga4/gsc/plausible) and explains that self-hosted providers accept an endpoint. However, it doesn't state when to use this vs. alternatives like test_provider_connection, set_provider_enabled, or set_primary_provider, leaving usage boundaries somewhat implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the behavioral detail that it returns the 'latest rank position', which is useful context beyond annotations. With annotations carrying the main safety burden, this is adequate.
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?
A single concise sentence with zero waste. It front-loads the primary action and adds the key return detail. Could be slightly richer, but for a simple single-keyword fetch, length is appropriate.
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?
This is a simple retrieval tool with good annotations and full schema parameter coverage, so the description's job is modest. However, it doesn't mention the output shape (no output schema exists), and it doesn't clarify the relationship/requirement between project_id and keyword_id — e.g., whether project_id is optional or required for scoping. For a simple tool this is adequate but leaves some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (keyword_id and project_id) with patterns and descriptions. Baseline 3 is appropriate since the schema does the heavy lifting; the description adds the semantic that the result includes the latest rank position but doesn't explain how project_id relates to keyword_id lookup.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource ('Get a keyword') and adds the specific scope of 'latest rank position by keyword id'. This distinguishes it from siblings like list_keywords (bulk listing) and get_keyword_metrics (metrics-focused). It doesn't explicitly name sibling alternatives, but the purpose is clear and specific.
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 single-keyword retrieval by id, which distinguishes it from list_keywords, but there is no explicit guidance about when to use this vs alternatives or exclusions (e.g., when to use get_keyword_metrics, get_rank_history, or run_rank_check instead). Usage context is implied but not stated.
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 the admin PAT requirement, which is a meaningful behavioral constraint not captured in annotations. However, it doesn't explain whether the returned tokens include sensitive values, whether tokens are truncated, or pagination 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?
Extremely concise: two short sentences totaling about 10 words of actual content. Zero waste, front-loaded with the core action before the prerequisite. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with strong annotations, the description is reasonably complete. It conveys the core purpose and the auth requirement. However, given that the tool deals with sensitive credentials (personal tokens), it could note whether token values are fully returned or masked, and whether the caller should expect the current user's tokens only vs. all users' tokens in an admin context.
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?
This tool has 0 parameters, so there's no parameter information to convey. Per the rubric, 0 params earns a baseline of 4. The description doesn't need to add parameter semantics since none exist.
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+resource: 'List the user's personal access tokens.' It identifies what is being listed (personal access tokens) and distinguishes this from sibling tools like list_api_keys, create_personal_token, and revoke_personal_token. The scope ('the user's') adds clarity about whose tokens are listed.
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 only usage guidance is the requirement for an admin PAT ('Requires an admin PAT'). There is no when-to-use guidance, no exclusions, and no mention of how this differs from list_api_keys or list_migration_tokens. The admin requirement is useful but incomplete as usage 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 and destructiveHint=false, covering the safety profile. The description adds that revoked keys are included, which is useful context. However, it doesn't disclose pagination behavior, ordering, or whether results are complete (given the limit/cursor params suggest pagination but no limit default or behavior is stated).
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 single-sentence description is efficient and front-loaded with the core purpose. The added detail about revoked keys earning its place. No padding 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?
This is a simple list tool with pagination params and no output schema. The description is adequate for the basic purpose but doesn't explain pagination semantics or how results differ from list_api_keys. Given the sibling-tool landscape with list_api_keys, list_personal_tokens, and list_migration_tokens, a fuller description of the project-scoped distinction would help.
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 only 33% schema description coverage, the description compensates poorly. The project_id, limit, and cursor params follow standard pagination conventions when compared with sibling list tools, but the description doesn't clarify behaviors like default limit values or cursor usage. The schema covers project_id adequately; limit and cursor rely on convention.
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 (API keys scoped to a project), and adds the detail that revoked keys are included. It's identifiable among siblings like list_api_keys (global) and list_personal_tokens, though it doesn't explicitly distinguish from list_api_keys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for project-scoped keys, which differentiates from the global list_api_keys sibling. However, it gives no explicit when-to-use guidance, no mention of how pagination works, or when to prefer this over list_personal_tokens. The use case is inferable 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context beyond stating it 'lists' views. It doesn't mention pagination semantics (cursor/limit), even though the schema exposes pagination parameters. With annotations covering read-only safety, a 3 is appropriate—the description adds usable but not rich behavioral detail.
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?
Single sentence, zero waste, front-loaded with the verb 'List.' The sentence is efficient and readable. It could arguably be scoring 5, but it omits the pagination/surface nuance that a slightly longer description could have handled without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters including pagination (cursor/limit) and an enum surface field, yet the description is a minimal single clause. With no output schema, the description must convey return shape expectations, which it doesn't. However, for a straightforward list operation backed by readOnlyHint annotations, the current level is minimum viable but leaves the agent unsure about pagination behavior, default surface, and what fields returned views contain.
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 50%, with project_id documented in the schema ('Identifier of the bisibility project to operate on; list_projects returns valid project ids'). The description adds no parameter-specific semantics beyond what the schema already covers. With 4 parameters and only half documented in the schema, the description doesn't compensate for the surface or limit/cursor semantics gap, landing at baseline 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 verb+resource: 'List saved keyword views for a project.' It distinguishes from siblings like create_saved_view (create vs list) and delete_saved_view (delete vs list). However, it's not fully specific about scope (whether it lists views across surfaces or defaults to a surface) and doesn't differentiate from the many other list_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to enumerate saved views for a project but provides no explicit when/when-not guidance or alternatives. It doesn't mention the surface parameter that distinguishes keyword views from competitor views, nor does it point to create_saved_view or delete_saved_view as related lifecycle operations. The required project_id context ('for a project') provides some usage grounding.
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 safety profile is covered. The description adds value by disclosing that provider rate limits and reauthorization rules apply, which is useful behavioral context not in the annotations. However, it doesn't describe pagination, response size limits, or what happens when the connection is invalid/unconfigured. Given the annotation coverage, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact - two sentences covering the core purpose and the key operational caveats (rate limits, reauthorization). There's minimal waste. It could potentially mention the date-range scoping that start_date/end_date imply, but what's there is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and a moderate complexity profile, the description is reasonably complete. It covers the purpose, scope (connected accounts only), and operational constraints. However, it doesn't describe the return format, pagination behavior, or how limit interacts with output, and with no output schema the agent must guess what 'query stats' returns. An additional sentence on output shape 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 coverage is 67%, so the schema documents most parameters. The description doesn't add much parameter meaning beyond the schema, except it clarifies that 'one of the project's own connected' accounts is the target context, which implies connection_id matters. The limit and query parameters have no descriptions but are self-explanatory from their names/types. The description doesn't compensate for the 33% coverage gap.
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 fetches 'live query statistics from one of the project's own connected search-performance accounts', combining a specific verb (fetch/list) with a clear resource (query stats) and an important scope qualifier (from connected accounts). It distinguishes reasonably well from siblings like list_keywords and list_ranked_keyword_suggestions, though it doesn't explicitly name them.
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 fetching from connected search-performance accounts and notes that rate limits and reauthorization rules apply, which implies when it's relevant (when a connection exists). However, it doesn't explicitly state when to prefer this over alternatives like list_ranked_keyword_suggestions or list_keyword_metrics, so the when-to-use guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are provided: readOnlyHint=true, destructiveHint=false, openWorldHint=false. The description adds the scoping detail that this lists per-project endpoints filtered to events/notifications delivery. However, it doesn't describe return format, ordering, or pagination behavior which would be valuable for a list operation. Since annotations already cover the safety profile, the description adds modest value but is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb+resource, and wastes no words. It efficiently captures what the tool does without redundancy. It could be slightly more expandable with pagination guidance, but for what it contains, it is clean and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list endpoint with no output schema and moderate complexity (3 params, pagination), the description is adequate but thin. It identifies the resource and scope, but doesn't explain the limit/cursor pagination mechanism or return shape. With no output schema, some guidance on what is returned would improve completeness. The annotation coverage partially offsets the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% - only project_id has a description in the schema. The description does not compensate for the undocumented limit and cursor parameters; it doesn't explain that these are pagination controls. The description adds no parameter-level semantics beyond what the schema provides. With partial coverage, more description compensation would be expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource: 'list the per-project HTTP URLs that notifications and events are delivered to.' It specifies the resource (webhook endpoints), the scope (per-project), and the content (HTTP URLs for notifications/events). While siblings exist (create_webhook, update_webhook, delete_webhook), the 'list' action is clearly differentiated from those mutation siblings, and the parent 'list_' prefix distinguishes it from the general pool. It's clear but not exhaustive about pagination semantics that siblings might share.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this lists webhook endpoints for a project, and the schema's project_id parameter explicitly references list_projects for obtaining valid IDs, giving some usage context. However, there's no explicit when-to-use guidance, no mention of pagination usage (limit/cursor) which would be core to a list operation, and no alternatives mentioned among the large sibling set. The context of requiring project_id is implied but not stated in the description.
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 states it 'replaces its expiration and token' for a pending invite, indicating a mutation that regenerates credentials. Annotations declare readOnlyHint=false and destructiveHint=false, which are consistent. However, it doesn't disclose side effects like whether the previous token becomes invalid immediately, whether this requires specific team-admin permissions, or what happens when a non-pending invite is targeted.
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?
A single concise sentence conveys the action clearly. No wasted words, though the sentence packs two ideas (resend + replace expiration/token) efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 required params, an idempotency key param, and no output schema, the description is adequate but thin. It doesn't clarify the meaning/usage of idempotency_key (though schema gives max/min length), nor does it explain what 'pending' means or whether this tool applies only to pending invites (a search semantics detail). Sibling revoke_team_invite and create_team_invite provide context, but the description could better distinguish resend semantics.
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 67%, so two required params (invite_id, project_id) have descriptions in the schema. The idempotency_key parameter is undocumented in schema and undescribed in the tool description, which is a gap. The description adds the behavioral meaning that the tool regenerates expiration/token, but doesn't clarify which parameters drive that behavior beyond the obvious invite_id.
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 verb 'Resend' plus the object 'a pending team invitation' clearly states the action and scope. It distinguishes from siblings like create_team_invite (creation) and revoke_team_invite (cancellation). The extra detail about replacing expiration and token adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for re-sending invites but doesn't explicitly state when to use it vs create_team_invite or revoke_team_invite. It doesn't say whether it's for expired invites specifically or any pending invite. No exclusions 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds the canonicalization behavior ('canonical keyword locations') and the verbatim-use directive, which is genuinely useful. With annotations covering the read-only safety profile, an agent knows this is safe. No need to re-state safety; the description adds canonicalization context that exceeds 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?
Two sentences, zero wasted words. The first sentence states the purpose, the second delivers actionable workflow guidance. Well front-loaded and 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 search tool with good safety annotations, the description covers the core function and downstream use. However, with 2 undocumented parameters at 33% schema coverage and no explanation of pagination, sorting, or result format (no output schema exists), the description remains somewhat thin. The canonicalization hint is valuable but doesn't fully resolve the ambiguity in how 'limit' and 'country' shape behavior.
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 33% (only 'q' has a description). The description doesn't add any meaning for 'limit' or 'country' parameters. The description text mentions 'canonical' and 'city-level tracking' which implies 'country' filters scope, but doesn't explicitly explain how country affects results or what limit defaults to. Of 3 parameters, 2 are undocumented, and the description doesn't compensate for this gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combo ('Search canonical keyword locations') and adds the critical workflow context that the returned location_key should be used verbatim when creating or updating keywords. This distinguishes it from pseudo-search siblings like research_keywords and list_keywords, but doesn't explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the downstream use case: use the returned location_key verbatim for city-level tracking when creating/updating keywords. This gives strong context on when to use the tool. It doesn't explicitly state exclusions or when NOT to use it, but the 'city-level tracking' qualifier implies its scope. It doesn't name alternatives like research_keywords.
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 assert readOnlyHint=false, so the agent knows this is a mutating operation. The description adds that at least one of name/domain must be provided, which is useful. However, it doesn't state whether the operation is destructive to unspecified fields (e.g., does omitting name keep it unchanged?), whether partial updates are supported, or whether idempotency_key governs retry 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?
Two sentences, zero filler, front-loaded with the action and constraint. Efficient and clean.
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 moderately simple mutation tool with no output schema and sparse schema descriptions, the description is adequate but leaves gaps: it doesn't mention what the response returns (updated project vs null), whether domain uniqueness is enforced, or retry/idempotency semantics. Adequate for a simple update but not fully self-sufficient.
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 only 25% (project_id is described), leaving name, domain, and idempotency_key undocumented in the schema. The description compensates somewhat by clarifying name/domain are the updatable fields and that at least one is required, but it doesn't explain idempotency_key semantics or the domain/name format constraints beyond what the schema enum-less maxLength already provides. The description adds marginal value but doesn't fully cover the schema gaps.
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-resource pair ('Update a project's name or domain') and explicitly scopes what can be updated. It distinguishes from delete_project and get_project among siblings, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (modifying existing project metadata) and states the 'at least one required' constraint, but does not explicitly contrast against create_project or list_projects, nor state when NOT to use it. Usage 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 declare destructiveHint=false (not destructive), readOnlyHint=false (mutating), and openWorldHint=false. The description adds the 'write-only' HMAC secret context, which is a useful behavioral disclosure—meaning the secret can be set but never read back. However, beyond that, the description doesn't elaborate on side effects such as whether updating triggers immediate delivery testing or whether secret rotation invalidates pending signatures.
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?
A single, efficient sentence that covers both core operations without waste. It's appropriately sized and front-loaded with the primary verb. It earns its place, though it could afford to add one more clause about when to use it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no output schema, and only 43% schema coverage, the description carries a heavy burden it only partially meets. It conveys the two distinct operations (update vs secret rotation) but doesn't clarify the idempotency_key parameter behavior, how enabled interacts with other updates, or what a successful response looks like. Adequate for distinguishing from siblings but incomplete for full operation semantics.
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 low at 43%, but the description itself adds no parameter-specific meaning. The 'rotate' language implicitly flags hmac_secret as the rotation target, which adds marginal value. However, params like enabled, description, url, and idempotency_key are left entirely to the schema, which doesn't explain their semantics beyond basic type/format. The description could have compensated for the coverage gap but doesn't.
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 'Update a webhook endpoint or rotate its write-only HMAC secret' uses a specific verb (update/rotate) with a clear resource (webhook endpoint). It also highlights the two distinct operations the tool supports, distinguishing it from list_webhooks, create_webhook, and delete_webhook siblings. However, it doesn't explicitly contrast with siblings by name.
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 clearly implies this is for modifying an existing webhook, distinct from create/delete/list siblings. However, it doesn't provide explicit when-to-use vs when-not-to guidance, nor does it mention that the 'enabled' field can toggle webhook behavior or that inline signature verification uses the secret. No alternatives are named explicitly.
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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, which is sparse. The description adds meaningful context: 'The raw key is returned once' — a critical behavioral fact warning the agent that the secret cannot be retrieved again after creation. This is valuable transparency 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, zero waste. 'Create a project-scoped API key for CI or automation' plus the critical one-time-return warning. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation (creates a resource) with no output schema, no enums, and moderate complexity (3 params). The description captures the essential purpose and the one-time-return caveat, but doesn't explain the idempotency_key semantics, what happens if creation fails/duplicates, or whether this key can be revoked via a sibling tool (revoke or list_project_api_keys). Given the annotation sparseness, a bit more context would help.
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 67% (2 of 3 params documented). The description mentions 'project-scoped' which implies project_id is required, and says 'raw key returned once' indicating creation semantics. However, it adds little beyond the schema for the two documented parameters, and idempotency_key (the one undocumented param) gets no additional explanation in the description despite being non-obvious in purpose.
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+resource (create a project-scoped API key) and purpose (for CI or automation), which distinguishes it from 'create_api_key' (likely a general API key creator) and 'create_personal_token'. It doesn't explicitly call out sibling differentiation but the 'project-scoped' scoping does differentiate it.
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 states the key is for 'CI or automation' which gives some sense of when to use it, but it doesn't provide exclusions or explicitly mention alternatives like create_api_key or create_personal_token. No guidance on when NOT to use this tool versus the other key/token creation tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, which tell the agent this is a state-changing but not destructive operation. The description adds value by clarifying snapshots are retained, confirming non-destructive behavior aligns with the annotations. It does not disclose effects on monitoring, alerts, or billing.
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?
A single, efficient sentence that captures the core action and the critical non-destructive caveat. Zero wasted words, essential information 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?
For a state-changing tool with no output schema, the description is somewhat thin. It clarifies the non-destructive nature (good), but doesn't address what happens to the monitor state, whether it can be re-enabled later, or what the response returns. The shared project description for monitor_id is a schema issue that the description doesn't help resolve. For a relatively simple toggle operation this is acceptable but not 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 67%, with monitor_id and project_id documented in the schema. However, both parameters share identical descriptions ('Identifier of the bisibility project to operate on'), which is a schema defect where monitor_id appears misdescribed as a project identifier. The description adds no additional meaning, and the third parameter idempotency_key is undocumented in the schema with no description 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 verb 'Disable' with a specific resource ('project sitemap monitor') and adds the key detail that existing snapshots are retained, distinguishing this from destructive operations. It differentiates from the sibling tools enable_sitemap_monitor and list_sitemap_monitors which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to turn off monitoring while preserving data, which is clear enough intent. However, it does not explicitly state when to use this versus alternatives like enable_sitemap_monitor or list_sitemap_monitors, nor does it mention any prerequisites or consequences beyond snapshot retention.
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 the cursor-pagination behavior ('cursor-paginated JSON') which is useful context. Given strong annotations, the description adds moderate value (pagination format) but doesn't elaborate on pagination mechanics, rate limits, or result size bounds.
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, zero wasted words. The first sentence states purpose and output format; the second gives a targeted pointer to an alternative for a different use case. Efficient 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 tool has 6 parameters, no output schema, and 33% schema coverage. The description communicates the format (JSON, cursor-paginated) and the CSV alternative, but for an export tool of moderate complexity, it doesn't fully spell out how cursor pagination works or what the response shape is. Adequate but leaves gaps given the parameter surface and missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 33%, and the description provides no parameter-level detail beyond what the schema already offers. The schema itself documents project_id and keyword_ids patterns. The description adds no meaning for limit, range, cursor, or granularity beyond their schema defs (limit has min/max, range and granularity have enums). With 33% coverage, description should compensate more but doesn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Export project rank history') and notably clarifies the output format ('cursor-paginated JSON for reports and analysis'). It differentiates from the sibling tool get_rank_history by mentioning pagination, and from the broader REST endpoint for CSV dumps. However, it doesn't explicitly distinguish itself from related siblings like get_keyword_metrics or the REST endpoint by name.
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 guidance on when to use this tool (reports and analysis, JSON format) versus the REST endpoint for full streamed CSV dumps. However, it doesn't mention when to prefer get_rank_history over this tool, or contrast against other rank/export related siblings. Some clear context, no explicit exclusions beyond the CSV note.
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. The description adds no behavioral context beyond 'get' — no mention of what fields are returned, 404 behavior for invalid IDs, rate limits, or performance considerations. With annotations covering the safety profile, a baseline 3 is appropriate; the description doesn't contradict annotations but adds minimal extra 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?
A single, direct sentence that states the action and the key discriminator (by project id). No wasted words, no fluff. It uses a clean verb-noun structure. Minor deduction for the typo and for not mentioning the safe-read nature, but the length is appropriate and 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?
For a simple single-resource lookup tool with 1 required parameter, full schema coverage, and clear readOnly annotations, the description covers the essentials. It's not a complex mutation or a multi-parameter tool needing extensive behavioral context. The main gap is not describing the return structure, but no output schema exists, so some return-format detail could help. Overall adequate for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the project_id parameter is fully documented in the schema, including its format pattern and the note that list_projects returns valid IDs. The description itself adds no parameter semantics beyond the schema. Baseline 3 applies when the schema carries the full burden, which it does here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get one bisibility project by project id' clearly states it fetches a single project by ID, using the specific verb 'get' plus the resource. It's distinguishable from list_projects (plural) and create/update/delete_project siblings. Minor demerit for the odd typo 'bisibility' (likely 'visibility'), but the purpose is clear and the subject matter is specific.
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 context (fetch a single identified project) but provides no explicit guidance on when to use this versus alternatives. There's no mention of 'use list_projects to enumerate all projects first' or exclusion guidance. The pattern-validated project_id parameter gives some implicit hint, but no alternative tools or exclusions are named.
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 read-only safety profile is covered. The description adds the dimension of 'connection options and status' but does not disclose pagination behavior, ordering, or what 'status' specifically entails (connected, available, error states, etc.). With annotations covering the safety profile, a 3 is appropriate — partial added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence with zero waste. It front-loads the verb and resource clearly.
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?
This is a listing tool with pagination parameters (limit, cursor) and no output schema. The description does not mention that results are paginated, whether there is ordering, or what a provider connection 'option' includes (auth modes, endpoints, status fields). For a listing tool with two undocumented pagination params, the description leaves meaningful gaps but is not dangerously 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 only 33% — only project_id has a description. The description itself adds no parameter details. The limit and cursor parameters for pagination are undocumented, though the description's mention of 'status' hints at possibly many providers. The description does not compensate for the low schema coverage on these two 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 states 'List provider connection options and status for a project,' which uses a clear verb (list) plus resource (provider connection options and status) scoped to a project. It distinguishes reasonably from siblings like connect_provider, test_provider_connection, and get_provider_rates by focusing on 'options and status' listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is used to see what provider connection options exist and their status. It does not explicitly state when to use it vs alternatives like get_provider_rates, get_capabilities, or test_provider_connection, nor does it mention prerequisites like needing a connected provider. Context is implied but no exclusions or alternative references are provided.
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, openWorldHint=false, and destructiveHint=false, so the safety profile is clear from structured data. The description adds that it returns status and latest snapshot summary, which is useful context beyond the annotations. But it doesn't disclose pagination, limits, or ordering behavior of the returned list. Adequate given annotation coverage.
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 filler. It conveys the verb, resource, and what's returned in one line. Slightly terse but efficient and perfectly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list-type tool with one well-documented parameter, full schema coverage, and clear read-only annotations, the description adequately covers what an agent needs. Reference to 'latest snapshot summary' gives a hint of return shape despite no output schema. Given low complexity, this is sufficiently 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%, with the project_id parameter fully documented (pattern, format, and hint to list_projects for valid ids). The description itself doesn't elaborate on the parameter, but the schema carries the full burden. Baseline 3 is appropriate since the schema handles 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 action ('List the project sitemap monitor') and the resource ('sitemap monitor'), and adds what's included ('status and latest snapshot summary'). While it identifies the resource precisely and distinguishes it from the sitemap enable/disable sibling tools, it doesn't explicitly contrast with these siblings. A solid, specific purpose statement.
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 that listing is querying monitors for a project, with the readOnlyHint annotation also signaling read-only usage. However, it doesn't give explicit guidance on when to use this vs the enable_sitemap_monitor/disable_sitemap_monitor siblings, nor when one would want this information. Usable but not definitive.
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 provide readOnlyHint=false and destructiveHint=false. The description adds minimal behavioral context beyond this—it explains that self-hosted providers take an endpoint, but doesn't disclose what the test actually verifies, whether it fails fast, what network calls occur, or what the response outcome indicates. With openWorldHint=true, more context about side effects would be helpful.
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 sentences, no waste. The description efficiently conveys the core purpose and the one notable nuance (self-hosted endpoint). It could potentially add a sentence about the difference between passing credentials vs. testing saved, but what's there is lean and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a moderately complex tool with 5 parameters including a nested credentials object, no output schema, and sparse schema descriptions (40% coverage). The description covers the alternate credential entry paths and endpoint nuance but doesn't clarify what happens when no credentials are supplied (saved connection test), success/failure semantics, or which top-level vs. nested parameter combinations are valid. Given the complexity, more completeness would be warranted.
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 only 40% (project_id and endpoint have descriptions; login, secret, api_key, credentials, provider_id are partially documented). The description adds value by clarifying that credentials can be passed either as top-level login/secret or via the credentials object, and that endpoint is specifically for self-hosted instances. This meaningfully supplements the sparse schema descriptions, though it doesn't fully explain all parameter relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource combination ('Test provider credentials or the saved provider connection'). It distinguishes the tool's purpose within the provider-management family (siblings like connect_provider, update_provider_settings, set_provider_enabled). However, it doesn't explicitly contrast with sibling tools like connect_provider to clarify the boundary, though the testing intent is reasonably clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions self-hosted providers accepting an optional credentials.endpoint base URL, which gives some context. However, it doesn't explicitly state when to use this vs. connect_provider or update_provider_settings, nor does it explain what happens without credentials (does it test the saved connection?). Usage context is implied but not fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false. The description states it requires a write PAT, which adds meaningful behavioral context about authentication requirements. However, it doesn't disclose the full behavior of a write operation on the user (e.g., whether it's reversible, what happens to existing name, whether related sessions are affected). With annotations present, this adds modest value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that packs the essential information: what's updated (display name), who it applies to (authenticated user), and the auth requirement. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-field update operation with no output schema, the description covers the core purpose adequately. However, the idempotency_key parameter is entirely undocumented, and there's no guidance on the write PAT requirement beyond a passing mention. Given the low operation complexity, this is borderline adequate but could clarify the idempotency key's role and behavior on repeated calls.
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 50% with 2 parameters. The 'name' parameter has a description in the schema ('Display name chosen for your visibility account'). The description identifies 'display name' as the updated field, which aligns. However, the idempotency_key parameter has no description in either the schema or the tool description, leaving it unexplained. The description adds some alignment but doesn't compensate for the undocumented parameter.
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 resource (authenticated user's display name), making the purpose specific and unambiguous. It distinguishes from get_me (read) and other update operations, though it doesn't explicitly comment on alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions requiring a write PAT, which implies the usage context (write operations need elevated token). However, it doesn't explicitly state when to use this vs alternatives, nor when not to use it. The auth requirement is helpful context but there's no exclusion 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 include readOnlyHint=false, openWorldHint=false, destructiveHint=false, meaning this is a mutating but not destructive operation within a bounded API. The description does not describe side effects (e.g., whether creating a view overwrites an existing one, whether validation rejects the request, response behavior). Given the readOnlyHint=false already signals mutation, the description adds the validation note but little else about behavioral effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, getting to the point in the first sentence. The second sentence adds useful validation context. It is appropriately sized for the tool's complexity, though it could be slightly more organized.
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 complex nested config schema with two variants (keywords vs competitors surfaces), the description is reasonably complete. It lacks details about return values but there is no output schema, so some expectation explanation would help. The dual-surface ambiguity mentioned in purpose is the main completeness 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 80%, so the schema documents most parameters well (project_id, name, config). The description adds value by enumerating known valid values for the country/serp filters within config, which is genuinely useful context beyond the schema. The idempotency_key parameter is not described in the schema and remains unexplained, a minor gap.
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 creates a saved keyword view for a project, using a specific verb+resource. However, the input schema shows the config can represent two surfaces (keywords or competitors), yet the description only mentions 'keyword view' and the surface parameter permits both 'keywords' and 'competitors'. This creates slight ambiguity about whether it also creates competitor views.
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 helpful known-valid values for country and serp filters, which acts as implicit usage guidance. However, it does not distinguish this from siblings like create_alert_rule, list_saved_views, or explain when a saved view should be created vs. other operations. No explicit when/when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds the behavioral nuance that enabling doesn't trigger an immediate fetch—it defers to the next scheduled sync. This is useful asynchronous behavior disclosure. However, it doesn't explain idempotency behavior (e.g., what happens if already enabled) or error conditions.
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 tight sentences with zero waste. The description efficiently states the action and adds the key async behavior caveat. Front-loaded with the main purpose statement.
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 enable-mutation tool with no output schema and no nested objects, the description covers the essential aspects: what it does and the async fetch timing. The main gap is clarification on idempotency and the confusing duplicate-looking parameter descriptions, but overall it's reasonably complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%—two of three parameters (monitor_id and project_id) are documented in the schema. The description itself adds no parameter semantics beyond the schema. Interestingly, monitor_id and project_id have identical descriptions and patterns (both appearing to reference a project id), which is somewhat confusing. The undocumented idempotency_key param receives no clarification.
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 ("Enable the project sitemap monitor") with a specific verb+resource. It distinguishes conceptually from sibling tools like disable_sitemap_monitor and list_sitemap_monitors. However, it doesn't explicitly reference these sibling tools to help differentiate.
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 notes that enabling does not fetch immediately and the next scheduled worker sync fetches the sitemap, which provides important timing context for when this tool is appropriate. However, it doesn't explicitly state when to prefer this over disable_sitemap_monitor or what state the monitor must be in to enable 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 and destructiveHint=false, so the safe-read profile is covered structurally. The description adds the auth requirement (personal access token) and the membership scope, which is useful behavioral context. It doesn't describe return format, but with no output schema the burden is somewhat on the description, though for a standard 'get me' endpoint this is acceptable.
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 sentences, concise and front-loaded with the core purpose. No wasted words. Slightly more could be added about output shape, but for a zero-parameter read endpoint this is appropriately brief.
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 zero-parameter, read-only endpoint with clear annotations, this description is quite complete. It covers what's returned (authenticated user + project memberships) and the auth requirement. The only minor gap is not describing the return structure, but given there's no output schema and this is a well-understood endpoint type, the description handles the essentials well.
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 schema coverage is 100%, so there's nothing for the description to explain about parameters. The baseline for 0 params is 4, and the description doesn't mislead or add confusion, so it holds at 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Get), resource (authenticated user), and adds the scope of 'all project memberships.' This helps differentiate from update_me, which is a sibling. However, it doesn't explicitly contrast with sibling tools like list_projects, though the purpose is fairly distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it requires a personal access token, which is a useful requirement note. However, it doesn't explicitly state when to use this vs alternatives like update_me or list_projects, nor does it mention any when-not-to-use scenarios. The usage 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 provide some safety signal (destructiveHint=false, readOnlyHint=false). The description adds the team-wide scope ('whole project team') and confirms this affects all firing alerts, which is useful behavioral context. However, it doesn't disclose whether this is reversible, whether it requires permissions, or what the confirmation/return looks like for a tool with a team-wide effect.
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?
A single tight sentence that conveys the action, scope, and team-wide effect with zero waste. Efficient and readable.
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 bulk mutation tool with no output schema and no idempotency_key documentation, the description could do more. It explains the team-wide effect which is the key distinguishing trait, but doesn't cover confirmation behavior, reversibility, or the role of idempotency. Adequate for the tool's simplicity but with gaps.
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 50% (one of two params documented). project_id is well-documented with format, pattern, and provenance (list_projects). The description doesn't elaborate on idempotency_key, but that param's purpose is somewhat self-evident. The description clarifies 'every firing alert' scope which helps parameter interpretation.
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 (mark alerts as read), the resource (project alerts), and the scope (every firing alert, whole team). It distinguishes reasonably from sibling tools like list_triggered_alerts and mute_triggered_alert, though it doesn't explicitly differentiate them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a bulk operation affecting the entire team, but doesn't explicitly say when to use it vs mute_triggered_alert (which is per-alert muting) or list_triggered_alerts for review. No explicit when-not or alternatives given, though the team-wide scope hints at usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse but present (readOnlyHint=false, destructiveHint=false). The description doesn't contradict annotations. It discloses the set-or-clear behavior via the primary boolean param, but doesn't explain what effect becoming primary has (e.g., does it change report defaults, routing?). With no annotations confirming safety profile details beyond the basics, moderate transparency is acceptable.
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?
A single sentence that is efficient and zero-waste. The set-or-clear phrasing packs both behaviors into one concise statement. Well front-loaded and appropriate length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 params, 50% schema coverage, and no output schema, the description does some work but could add more. It explains the primary parameter's role but doesn't address what 'primary' means operationally or what the return value represents. However, given the relative simplicity of this configuration action and the decent schema descriptions for project_id and provider_id, this is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, and the description's phrase 'Set or clear' provides meaning to the 'primary' boolean param that the schema doesn't state (the schema has no description for 'primary'). This is genuine added value. However, the other uncovered param (idempotency_key) has no schema description and no description help, though the name is fairly self-explanatory.
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 "Set or clear a provider as the primary project provider" clearly states the verb (set/clear) and resource (provider as primary project provider). It distinguishes from siblings like set_provider_enabled and set_provider_priority by specifying this is about the *primary* designation specifically. It's clear but slightly terse.
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 communicates this alters project provider configuration, and the sibling set_provider_priority suggests priority vs primary are distinct concepts, but no explicit when-to-use or when-not-to-use guidance is given. No alternatives are named. The 'Set or clear' phrasing implies the primary param toggles it, but usage context around why you'd set a primary provider is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) partially cover the safety profile. The description adds valuable behavior: 'The raw token is returned once in the response and cannot be retrieved again; store it securely.' This is important operational context beyond the annotation declarations. No contradiction with annotations since readOnlyHint=false aligns with a create/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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient and front-loaded with the core purpose followed by the critical security note. No redundant phrasing or filler. Slightly more could be said about idempotency or scope selection, but the current length is well-balanced.
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 create tool with 5 params (80% schema-covered), no output schema, and readOnlyHint=false, the description covers the key behavioral risk (one-time token return). It doesn't detail the response shape, but for a creation tool without an output schema this is acceptable. Could note that scopes map to access tiers, but the schema enum already covers that.
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 80%, so most parameters (name, scope, project_id, expires_in_days) carry inline documentation. The description adds the critical warning that the token is one-time-returnable, but doesn't address idempotency_key (which has no schema description) or add semantics beyond what the schema provides. Baseline 3 is appropriate; no major compensation needed.
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?
Clear verb+resource: 'Create a new API key for the authenticated project.' It distinguishes itself from sibling tools like create_project_api_key, create_personal_token, and revoke_api_key by clarifying it creates keys for 'the authenticated project,' though it doesn't explicitly differentiate from list_api_keys or the project-scoped variants.
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 via 'for the authenticated project' but doesn't explicitly state when to choose this over create_project_api_key or create_personal_token, nor explain the distinction between API keys and personal tokens. Given the large sibling set with overlapping create-key tools, this is a notable gap — no exclusions or alternative guidance is provided.
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 destructiveHint: true annotation already flags this as a destructive operation, and the description's 'Use only after the user confirms deletion' reinforces it. However, the description doesn't disclose what happens after deletion (permanence, whether it's recoverable, related data affected). The description aligns with rather than contradicts 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 short sentences, zero filler. The description is front-loaded with the core action and immediately follows with the critical usage constraint. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with a single required parameter and good annotation coverage, the description covers the essential points: what it does and the confirmation requirement. A more complete description might note that deletion is permanent or irreversible, and the idempotency_key behavior isn't explained, but the tool is relatively simple.
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 67% (keyword_id and project_id both have descriptions; idempotency_key lacks a description). The description points to keyword_id but doesn't add semantic context beyond the schema's own parameter descriptions. Baseline 3 is appropriate since schema does the heavy lifting for 2 of 3 params.
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 deletes one keyword by keyword id, distinguishing it from sibling tools like delete_project, delete_alert_rule, delete_webhook, etc., which target different resources. The scope ('one keyword by keyword id') 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use only after the user confirms deletion', which is a clear usage constraint that can trigger confirmation workflows. However, it doesn't explicitly mention alternatives (like delete_saved_keyword for saved keywords, though the name distinction implies this).
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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is already disclosed. The description adds the user-confirmation requirement on top, which is useful context. However, it doesn't mention whether deletion is reversible, cascading, or what happens to related views/keywords. Given annotations already cover the destructive nature, the description adds modest incremental value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with zero filler. Every word earns its place: the action, the resource, and a critical safety directive. Perfectly sized for a destructive delete 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?
For a fairly simple delete operation with clear annotations and 67% schema coverage, the description is mostly adequate. However, the undocumented idempotency_key parameter and lack of detail on side effects (e.g., whether deleting a view affects anything downstream) leave minor gaps. The destructive confirmation guidance compensates somewhat, but this 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 coverage is 67% (view_id and project_id are described; idempotency_key has no description). The description doesn't add parameter-specific meaning beyond the schema. The idempotency_key is undocumented in both schema and description. With 2 of 3 params documented in schema, the baseline 3 applies; the description adds no parameter clarification.
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 what the tool does: 'Delete a project saved view.' This is a specific verb (delete) plus resource (saved view). The purpose is straightforward and aligns with the sibling create_saved_view. It scores 4 because while clear, it doesn't differentiate much from other delete tools like delete_project or delete_keyword, though the resource name disambiguates sufficiently.
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 important context: 'Use only after the user confirms deletion.' This is a clear usage directive indicating it's a destructive action that requires user consent. It doesn't explicitly mention alternatives or when-not-to-use, but the confirmation requirement is valuable safety guidance. No alternative tools are named for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, so the agent already knows this is a safe read operation. The description adds the important scoping detail ('saved without rank tracking'), but doesn't disclose pagination behavior, response format, or sort ordering. Given the readOnly annotation carries much of the safety profile, a mid score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One clean sentence that states the action and scope. Zero waste, perfectly sized for a simple list operation. It would be hard to make this more concise while retaining meaning.
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 filtered-list tool with readOnly and non-destructive annotations and conventional pagination parameters, the description is largely adequate. It explains the key distinguishing feature (saved without rank tracking). It doesn't describe pagination or ordering, but these are typical for list endpoints and inferable from limit/cursor parameters. Could mention that pagination follows the returned cursor, but this is reasonable for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 33%, the description does not explain any of the 3 parameters. The project_id parameter has its own schema description, but limit and cursor have none. However, limit and cursor are conventional pagination parameters whose semantics are naturally inferred. The description adds no parameter detail, slightly compensating via schema on project_id but leaving the other 67% uncovered.
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 lists keyword ideas 'saved without rank tracking for a project.' This distinguishes it from list_keywords, list_ranked_keyword_suggestions, and research_keywords siblings by the 'saved without rank tracking' qualifier. The purpose is specific and unambiguous, though it doesn't explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for viewing saved-but-not-tracked keywords, which implicitly distinguishes it from list_keywords (tracked) and list_ranked_keyword_suggestions. However, it does not explicitly state when NOT to use this tool or name alternative tools like the related list_keywords or create_saved_keywords. Context can be inferred but is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate openWorldHint=true (may create new entities) and destructiveHint=false. The description adds context by clarifying the role options and that invites target project teams. It doesn't disclose whether invites are sent via email, have expiry, or require review, but the schema notes the 'invited or existing team member' nuance. With annotations covering the non-destructive mutation profile, the description adds reasonable value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with zero wasted words. It front-loads the verb and resource and immediately enumerates the role choices, exactly what an agent needs. No redundant content.
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 no output schema and 4 params (one of which, idempotency_key, is undocumented), the description could explain more — e.g., what a successful invite returns, whether an invitation has a recipient action, or the idempotency_key's purpose. The sibling tools (resend/revoke) imply invites create pending states, but the description doesn't clarify the post-invite flow.
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 75% with 3 of 4 params documented. The role enum is well-specified, email has format+pattern+maxLength, project_id has pattern and a reference to list_projects. The idempotency_key parameter has NO schema description and no mention in the tool description, which is a gap, but the schema itself is rich for the other three. Description adds the 'admin, member, or viewer' clarity.
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 states a specific verb ('Invite') plus resource ('a user to a project team') and enumerates the viable roles. It clearly distinguishes from sibling tools like list_team_invites, revoke_team_invite, and resend_team_invite. It doesn't explicitly mention that it also works for existing members (which the role schema description hints at), but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for granting project access, and the schema notes roles apply to 'invited or existing team member.' However, there's no explicit guidance on when to choose this vs. update_team_member_role, or whether this tool also requires an existing team when adding a member. The project_id param references list_projects, which offers some pathway context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and readOnlyHint=false, which covers the safety profile. The description adds value by noting the user-confirmation requirement, which goes beyond the annotation signal. Mutations aren't described as reversible, and no return-format information is given, but annotations do the heavy lifting 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?
Two short sentences, zero wasted words. The purpose and the critical usage constraint (confirmation) are both delivered compactly and 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?
For a destructive tool with annotations declaring the destructive nature, this is reasonably complete. It adds the user-confirmation requirement which is critical safety context. No output schema exists, but for a delete operation, return value explanation is generally less critical. Could mention irreversibility, but the destructiveHint annotation plus confirmation instruction largely covers 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?
Schema coverage is 67%, meaning rule_id and project_id have descriptions while idempotency_key has none (only length constraints). The description doesn't elaborate on any parameters beyond what the schema provides. The idempotency_key, undocumented in schema, is also not explained in the description — a minor gap.
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 (delete) and the resource (alert rule) plus the identifier method (by rule id). It distinguishes from siblings like update_alert_rule and create_alert_rule through the verb-resource pairing, though it doesn't explicitly call out the sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description adds the important context that this should 'Use only after the user confirms deletion' — a clear usage constraint appropriate for a destructive action. It implies this is a user-confirmation-gated operation but doesn't name alternatives or exclusions explicitly.
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 and destructiveHint=false, so the read-only safety profile is covered. The description adds value by noting that the list includes revoked keys, which is a behavioral trait beyond what annotations convey. This is useful context an agent wouldn't get from the schema or annotations alone.
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?
Single sentence, front-loaded with the core verb+resource, and the 'including revoked keys' clause is relevant additional detail. Zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with no output schema and 3 simple params, the description is reasonably complete. The 33% schema coverage means limit and cursor lack documentation, but these are standard pagination params that agents commonly understand. No output schema means the return format is not described, which is a minor gap for a list 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 only 33% (only project_id has a description). The description doesn't cover limit/cursor semantics, which are common pagination params an agent could infer. The project_id parameter's schema description ('list_projects returns valid project ids') already covers the most nuanced parameter, so the description adds minimal additional value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('List API keys') and adds a meaningful scope detail ('including revoked keys'), which distinguishes it functionally. It's clear what the tool does. However, it doesn't distinguish itself from the sibling 'list_project_api_keys', which sounds near-identical in purpose — a missed opportunity for differentiation.
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 notes it operates on 'the authenticated project' and includes revoked keys, which gives some context on scope. It doesn't explicitly state when to use this versus list_project_api_keys or list_personal_tokens, despite these being plausible alternatives. The project_id parameter description helps, but no explicit when/when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so safety profile is clear. The description adds meaningful context that snapshots come specifically from 'the project's own connected analytics accounts' — establishing a data-provenance boundary that's genuinely useful 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?
Single efficient sentence that conveys source, resource type, and filtering options. Compact and front-loaded, though it could add a bit more practical guidance without bloating.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and moderate parameter count (6). The description conveys what the tool does and its source scope but doesn't clarify return format, sorting, pagination behavior, or whether date range is inclusive — gaps for an agent deciding how to paginate a potentially large result set.
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 50% (end_date, start_date, project_id are described). The 3 undocumented params (limit, offset, paths) are self-evident pagination and filter controls whose meaning is clear from names and schema constraints. Description adds no param-level detail beyond what the schema provides, so 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?
Specific verb 'list' + resource 'stored page traffic snapshots' + clear scoping ('project's own connected analytics accounts', 'date range', 'optional page paths'). Distinguishes it from sibling tools like list_search_performance_query_stats and sync_project_traffic.
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 what data it returns (project's own connected analytics accounts) and filtering criteria. It doesn't explicitly contrast with alternative tools like sync_project_traffic or list_search_performance_query_stats, so usage context is implied rather than explicitly compared against 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 indicate readOnlyHint=false (a write operation) and destructiveHint=false. The description adds meaningful context beyond annotations: it discloses the shared-team scope ('changes shared alert state for the whole project team') and the auto-revert duration (24 hours), which is valuable behavioral information an agent wouldn't infer from the schema. The typo 'bisibility' in schema doesn't affect description scoring.
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, zero waste. The first sentence states the action and duration; the second flags the shared side effect. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-state mutation with no output schema (muting is a simple toggle), the description covers the key points: what it does, how long it lasts, and its team-wide scope. The undocumented idempotency_key parameter is a minor gap, but given the tool's simplicity, the description is reasonably 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 67% — alert_id and project_id are documented in the schema, but idempotency_key has no schema-level description. The description adds no parameter-specific detail beyond what the schema provides (it doesn't explain what idempotency_key does or its format). With moderate coverage, the description doesn't need to compensate heavily but could add context on the idempotency parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Mute one firing alert') with a clear duration ('for 24 hours'). It clearly states the scope (one firing alert) and duration, distinguishing it from similar alert operations. However, it doesn't explicitly name sibling alternatives, so it earns a 4 rather than 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 states the duration implicitly ('for 24 hours') and notes the shared project-level side effect, giving some usage context. However, it does not provide explicit when-to-use vs. alternatives guidance, nor what to do if the alert is already muted or how this differs from other alert-related mutations like mark_project_alerts_read or delete_alert_rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, so the mutation trait is disclosed via annotations. The description adds meaningful behavioral detail beyond annotations: the full-replacement semantics and the fact that condition_type and name are required even for single-field updates. This is valuable because update tools often silently partial-patch, and this one does not. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core verb+resource action and a critical behavioral caveat. Every sentence earns its place and there's no fluff. Slightly thin given the tool's complexity of 17 condition-dependent params, but the structure is clean and 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?
The tool has 17 parameters, no output schema, and only 29% schema description coverage. The description captures the most important semantic (full replacement and required fields) but does not address condition-parameter coupling—e.g., which params make sense for 'change_pct' vs 'threshold' vs 'serp_feature' conditions. For a complex tool there is no guidance on selecting target_ids/target_type or recipient_ids/channels relationships. It's adequate for basic use but leaves meaningful 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 only 29%, and the description adds value beyond the schema by explaining the replacement semantics affecting required parameters. However, the 17 parameters are largely undocumented in the description—it doesn't explain the condition-specific parameter combinations (e.g., which params apply to which condition_type values). The description covers the critical name/condition_type/rule_id nuance but leaves condition-parameter relationships unexplored for a complex 17-param 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 clearly states 'Update an alert rule by rule id' with a specific verb and resource. It distinguishes the operation from siblings like create_alert_rule and delete_alert_rule by implying a replacement semantics. However, it doesn't explicitly name the sibling alternatives for differentiation, and the 'replaces whole rule configuration' clause overlaps with behavioral transparency.
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 guidance that this is a full-replacement operation ('replaces the whole rule configuration'), which is crucial usage context. It implies when not to use it (not for partial updates), though it doesn't explicitly name alternatives like create_alert_rule for new rules. The condition_type and name being required as clues to create-like semantics is helpful.
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=false and destructiveHint=false, indicating a mutation that isn't destructive. The description adds the constraint about non-owner members and UI-only ownership transfer, which is useful context. It doesn't disclose permission requirements, reversibility of the role change, or idempotency behavior, but the annotations carry the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first sentence states the action with precise role values and target constraint; the second sentence provides the critical exclusion (UI-only ownership transfer). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and moderate schema coverage, the description covers the core action and a key constraint. However, it doesn't address the idempotency_key parameter at all, doesn't mention what happens to an owner if somehow targeted, and doesn't describe response behavior for a state-changing operation. Adequate but with gaps.
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 75%, with role having an enum and member_id/project_id having patterns and descriptions. The description reinforces the role values (admin, member, viewer) and the non-owner constraint that clarifies member_id scope. It doesn't explain the idempotency_key parameter, which is undocumented in the schema, but the description adds meaningful scoping context 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?
Clear verb+resource+scope: "Change a non-owner project member role to admin, member, or viewer." It specifies the exact roles available and the constraint that the target must be a non-owner. It doesn't explicitly differentiate from siblings like remove_team_member or list_team_members, but the purpose is evident from the name and description.
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 states what it does (change non-owner roles) and explicitly notes ownership transfer is UI-only, providing a clear exclusion boundary. This tells the agent when NOT to use this tool (for ownership transfer). However, it doesn't name alternative tools or describe when to prefer this over list_team_members/remove_team_member/edit flows.
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 declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, leaving the description as the primary behavioral disclosure source. The description usefully discloses that the raw token is returned only once (a critical one-time-visibility behavior) and that admin permission is required. These add real 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?
Two sentences, zero wasted words. Every sentence earns its place: one states the purpose, the other discloses the critical one-time-return behavior and the admin prerequisite.
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 token creation tool with no output schema referenced, the description covers the key behavioral facts: single-return of raw token, admin requirement. With 4 parameters and low schema coverage, it could have elaborated more on scope/expiration semantics, but the essential agent decision-making info is present.
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 only 25% (only 'name' has a description). The description adds the crucial semantic that the returned value is a raw account-wide token visible only once, which helps understand parameter intent. While it doesn't detail expires_in_days or scope semantics specifically, the description compensates somewhat for the low schema coverage by explaining the token's nature.
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 'Create a personal access token' with a specific verb and resource. It distinguishes from siblings like revoke_personal_token and list_personal_tokens, though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Requires an admin PAT' which gives a prerequisite, and the context of 'raw account-wide token returned once' implies single-use visibility. However, it doesn't explicitly state when to use this vs create_api_key or create_project_api_key, which are closely related 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?
The annotations already declare destructiveHint=true, so the destructive nature is covered. The description adds the confirmation requirement ('only after the user confirms deletion'), which is valuable safety context beyond the annotation. It doesn't discuss irreversibility explicitly, but that's implied and the confirmation gate compensates. 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?
Two concise sentences with no waste. The first states the action, the second the critical usage precondition. Efficient and front-loaded. Could arguably score 5, but the description is slightly terse and could benefit from noting the irreversible nature more directly.
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 delete operation with destructiveHint=true annotation, the description plus annotations adequately convey the essentials: what it does, confirmation requirement, and two key parameters documented. No output schema exists, but delete operations typically return minimal responses, so this is acceptable. The description is reasonably complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% — project_id and saved_keyword_id are described in the schema, but idempotency_key has no description. The description adds nothing about parameters beyond what the schema provides. Baseline 3 applies given the schema covers most parameters, though the undocumented idempotency_key is a minor gap.
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 "Delete one saved keyword" clearly states the verb (delete) and resource (saved keyword), with specificity about scope (one). It distinguishes from siblings like delete_keyword (regular keyword) and delete_saved_view (different resource), though it doesn't explicitly name the distinctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use it: "Use only after the user confirms deletion." This is important confirmation-before-deletion guidance. However, it doesn't explicitly state when NOT to use it or name alternative tools (like delete_keyword for regular keywords with project_id context), so a small gap remains.
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 destructiveHint=true and readOnlyHint=false, so the safety profile is established. The description reinforces this with the confirmation requirement ('Use only after the user confirms deletion'). However, it doesn't disclose what happens to downstream artifacts (e.g., whether associated webhooks, alerts, or keywords are affected), which would add meaningful transparency for a destructive disconnect 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 a single, tight sentence with a guardrail attached. Two sentences, zero waste. Every word earns its place—the verb, target, scope, and usage constraint are all present.
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 mutation tool with no output schema and incomplete parameter coverage (idempotency_key undocumented), the description could do more. It doesn't address reversibility, side effects on related resources, or the response format. However, it's a focused action ('disconnect a provider') and annotations carry some safety context. Adequate but not rich.
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 67%, so project_id and provider_id are already documented in the schema. The description adds no parameter-level detail beyond that. The idempotency_key (the third, undocumented param) is not explained anywhere—its purpose and when to set it are unknown. Baseline 3 applies since schema does most of the param work, but the undocumented idempotency_key gap slightly limits compensation.
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+resource structure: 'Disconnect a provider from a project.' This clearly distinguishes it from sibling tools like connect_provider, update_provider_settings, set_provider_enabled, and set_provider_priority. The scope (project + provider) is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a clear when-to-use constraint: 'Use only after the user confirms deletion.' This is an explicit usage guardrail for a destructive operation. It doesn't name alternatives like delete_project or set_provider_enabled for similar scenarios, but the confirmation requirement is valuable and specific.
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 safe-read nature is covered. The description adds value by explaining the auth-mode-dependent result scope (key returns one project, PAT returns all memberships), which is meaningful behavioral context beyond annotations. However, it doesn't describe pagination, sorting, or response format details.
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, zero wasted words. The first sentence states the purpose; the second explains the critical auth-type difference. Efficient and 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?
For a zero-parameter, read-only listing tool with good annotations, the description is complete. It covers the key behavioral nuance (auth-type-dependent scope). No output schema exists, so the description could benefit from mentioning what fields are returned, but for a simple listing tool this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema coverage (empty schema is fully covered). With 0 params, the baseline is 4. The description appropriately focuses on behavior rather than params since there are none to document.
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 (list) and resource (projects visible to the configured credential). It distinguishes behavior based on auth type (project keys vs personal access tokens return different scope). It doesn't explicitly differentiate from sibling tools like get_project, but the scope statement adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use it: to list projects visible to the configured credential. It explains the two authentication modes and their differing behavior (key returns one project, PAT returns all memberships), which helps the agent anticipate results. No explicit exclusion of alternatives, but the 'visible to credential' scoping is useful context given the openWorldHint=false annotation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false (mutation) and destructiveHint=false, so the description's 'update' semantics align with annotations — no contradiction. However, the description adds limited behavioral context beyond the annotations: it does add the location_key provenance detail ('pass verbatim'), which is a useful behavioral note. It doesn't disclose partial-update semantics (whether omitted fields are preserved or cleared) or auth requirements, which given 15 optional params 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly scoped, front-loaded with the core purpose. The first sentence lists the mutable fields; the second gives the key usage prerequisite. Every clause earns its place with zero 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?
Given 15 params, a nested schedule object, and no output schema, the description is lean. It competently covers the core purpose and the location prerequisite, but doesn't address ambiguities the schema leaves open: difference between 'frequency' (top-level) and 'schedule.frequency', partial-update behavior for nullable fields (city, country, target_url accept null — implying clearing), or project scoping. For a high-parameter mutation tool, the description should resolve some of these.
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 only 33%, so the description partially carries burden. It maps fields (text, country, device, target URL, tags, schedule) to parameters, which adds value. The location_key verbatim instruction adds genuine semantic detail beyond the schema's regex pattern. However, many parameters (intent, topic, project_id, idempotency_key, frequency vs schedule) lack description coverage, and the description doesn't clarify the relationship between the top-level 'frequency' and the nested 'schedule' 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?
The description clearly states 'Update keyword metadata such as text, country, device, target URL, tags, or schedule' — a specific verb+resource with enumerated field examples. It also distinguishes from siblings by referencing search_locations for location handling, differentiating it from set_keyword_target_url (which is a more narrow single-field update).
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 a clear usage hint: 'Use search_locations and pass its location_key verbatim for city-level tracking.' This names a specific companion tool and explains the prerequisite for location. It doesn't explicitly say when NOT to use it or list alternatives (e.g., set_keyword_target_url for URL-only updates, bulk_update_keywords for multiple), but the primary context is clear.
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=false, destructiveHint=false, openWorldHint=false. The description adds useful constraints like the 8KB payload limit and the source/type validation rules, plus the happened_at default-to-now behavior. But it doesn't fully disclose the full behavioral surface for a mutation tool - e.g., whether idempotency is guaranteed, any rate limits, or what happens on duplicate signals.
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?
A single compact paragraph that front-loads the core purpose, then efficiently lists the optional parameters with their types and defaults. Every sentence earns its place; there's zero padding. The enum constraints and format examples are packed into a concise but complete description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create-type tool with 9 params (only 2 required), the description covers the essential semantics well: required source/type constraints, optional happened_at, url, severity, and payload limits. It would benefit from noting whether idempotency_key provides deduplication guarantees, but given the high schema coverage (89%), enums on 2 params, and default behaviors documented, the completeness is strong 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 high at 89%, so the schema carries most of the parameter documentation weight. The description adds value by explaining the 'type' pattern examples ('deploy.completed', 'cms.page_updated'), source enum values, and specifying event context. However, it doesn't elaborate on the idempotency_key purpose or keyword_id semantics beyond schema, which the schema describes reasonably well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb+resource ('Ingest a signal') and clearly defines the resource as an external event (deploy, CMS content change, or custom API event) explaining ranking movements. It distinguishes itself from sibling tools by its unique purpose of creating signals versus reading/searching them (list_signals exists as sibling).
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 it's for ingesting external events that may explain ranking movements, giving concrete examples (deploy, CMS content change, custom API event). It implies this is for signaling the system about external events but doesn't explicitly contrast with alternatives or state when NOT to use it. However, the sibling list_signals clearly pairs with it, and the 'key-scoped project' scoping gives context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, which already communicate that this is a safe read operation. The description adds the anonymous endpoint detail and clarifies that provider defaults to dataforseo, plus openWorldHint=false indicates a closed model with known provider keys. No contradictions with annotations. Description adds reasonable context but doesn't describe output/return structure or error cases.
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 well-organized sentences: what it estimates, required inputs, and provider/rate-card selection with a pointer to the sibling tool. Zero filler, efficient front-loading of purpose and key 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?
Complete for a read-only estimation tool with 100% schema coverage and no output schema. The description covers inputs, provider defaults, rate-card lookup path, and the anonymous nature. Missing is an indication of output shape, but since there is no output schema and readOnlyHint covers safety, it's adequately complete. Slightly more return-format context would push it to 5.
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 7 parameters thoroughly with descriptions, defaults, ranges, and enums. The description reinforces key semantic details (provider defaults to dataforseo, frequency maps to monthly checks, see get_provider_rates for keys) but the schema carries most of the weight. 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?
Specific verb+resource+scope (estimate monthly rank-check cost for keyword portfolio). It distinguishes itself from related siblings like get_provider_rates (referenced directly) and research_keywords. Clear that it's a cost-estimation computation, not a live rank check or pricing lookup.
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?
Gives clear input guidance (keyword count, devices per keyword, locations, frequency) and explicitly directs the user to get_provider_rates for available keys. States the anonymous endpoint nature. Could be stronger on explicit when-NOT-to-use guidance, but the cross-reference to get_provider_rates differentiates it well from a pure rate-card lookup.
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, covering the safety profile. The description adds useful context: which channels it covers (email, Slack, webhook) and explicitly excludes addresses/URLs ('Returns no addresses or URLs'), setting expectations about the response. However, it doesn't state whether all three channels are always present or what happens with disabled channels.
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, zero wasted words. The first sentence states purpose and scope; the second sentence preempts a common confusion (addresses/URLs) and directs to the correct sibling tool. Excellent front-loading and economy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one well-documented parameter, strong annotations, and no output schema, the description covers what's needed. It explains return semantics (channel toggles), scoping (per-project), and distinguishes from the likely-confused sibling. The only minor gap is not describing the exact return structure/format of the channel switches, but with no output schema requirement, 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 description coverage is 100% and the project_id parameter is well documented in the schema ('Identifier of the bisibility project to operate on; list_projects returns valid project ids'). The description adds the project-scoping context but doesn't need to explain the single parameter further since the schema fully covers it. 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?
Clear verb+resource: 'get which channels (email, Slack, webhook) are turned on for the project.' The description explicitly states what is returned (channel toggles) and distinguishes from the sibling get_notification_preferences vs update_notification_preferences (read vs write) and list_webhooks (addresses/URLs vs toggles). The 'Returns no addresses or URLs' phrasing actively differentiates it from list_webhooks.
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 scoping context ('for the project') and explicitly points to list_webhooks as the alternative for destination details ('use list_webhooks for where notifications are sent'). It doesn't explicitly say when-not-to-use, but the sibling differentiation gives practical guidance. Could mention that this is a read complement to update_notification_preferences, but that's implied.
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 safety profile is fully stated. The description adds that this lists only 'pending' invites (not all invites), which is useful filtering context beyond the annotation. However, it doesn't disclose pagination behavior or whether the response includes both sent and received invites.
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?
Single sentence, zero wasted words. The description is appropriately minimal for a simple read-only listing tool. Every element (list, pending, team invites, project) carries meaningful 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?
For a read-only listing tool with good annotations, no output schema, and 3 params (1 required), this is reasonably complete. The main gaps are pagination behavior (cursor/limit interplay) and whether results include invite status variants. But given the low complexity and strong annotation coverage, a modest description suffices.
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 only 33% (only project_id is described in schema). The description uses 'pending' to signal scope but doesn't elaborate on limit/cursor semantics beyond what the schema's min/max reveals. The description adds modest value by clarifying the listing scope but leaves the cursor pagination pattern implied rather than explicit.
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 pending team invites for a project' uses a specific verb (list) and resource (team invites) with clear scope (pending, for a project). It distinguishes from siblings like list_team_members, create_team_invite, and revoke_team_invite by focusing on pending invites rather than members or invite mutations.
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 indicates this operates per-project ('for a project'), which is the core usage context. It doesn't explicitly name alternatives or state when not to use it, but the read-only listing purpose is clear from the tool name and siblings. Lacks explicit exclusion of other invite-related 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 declare destructiveHint=true, and the description reinforces this with 'Permanently remove,' adding irreversibility context. It also specifies the tool operates only on non-owner members, an important behavioral constraint. This adds value beyond the annotation by clarifying the scope limitation and permanent nature, though it could mention cascading 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, zero wasted words. The purpose and the critical usage caution are both delivered efficiently with appropriate front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema or rich annotations, the description plus good schema covers the key aspects: what it does (permanently remove), who it applies to (non-owner), and the safety requirement (confirm intent). For a simple 3-parameter tool with 67% schema coverage, this is adequately complete, though it could mention permission prerequisites.
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 67% (member_id and project_id have descriptions, idempotency_key has none). The description adds the 'non-owner' constraint relevant to member_id, which is useful, and project_id schema reference to list_projects is already present. idempotency_key semantics are not elaborated in the description, so the 33% uncovered remainder isn't compensated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb + resource + scope: 'Permanently remove a non-owner project member.' It distinguishes scope by restricting to non-owner members, which differentiates from sibling update_team_member_role and list_team_members. However, it doesn't explicitly name alternative 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 second sentence instructs to 'Confirm the user's intent before calling this tool,' which provides an important usage caution appropriate for a destructive operation. It doesn't explicitly name when-not-to-use or alternative member-management tools (like update_team_member_role), but the confirmation guidance is clear practical context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations present (readOnlyHint=false, destructiveHint=false), the description is not contradicting them. It adds the useful note about passing location_key verbatim for city-level tracking. However, for a mutation tool with rich nested objects (schedule, location, device, intent, topic), it does not disclose side effects like whether existing keywords are deduplicated, whether rank checks are triggered on add, or idempotency behavior via idempotency_key. The description carries the burden but stays 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?
Two sentences, zero filler. The first sentence states the core function and optional parameters; the second gives actionable workflow guidance. 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.
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 — 13 parameters, nested keyword objects with per-item schedules/device/location, no output schema, 31% schema coverage — the description is incomplete. It doesn't explain return value/behavior (does it return created keyword IDs?), per-keyword vs bulk parameter overriding rules, or the meaning of intent/topic/device. Annotation coverage is minimal (no openWorldHint info given as context). The description does the minimum but leaves significant gaps for such a complex 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 low at 31%, with 13 parameters and nested objects. The description does compensate partially by naming the key optional enrichments (tags, target URL, schedule) and by highlighting location_key's critical role. However, many parameters (topic, intent, device, country, city, location, idempotency_key) lack schema descriptions, and the description doesn't explain their meaning, so the burden isn't fully met despite the good location_key guidance.
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: 'Add one or more keywords to a project, optionally with tags, target URL, and schedule.' It uses a specific verb + resource, enumerates the optional attributes, and adds the specific instruction to use search_locations and pass its location_key verbatim. This distinguishes it from siblings like bulk_update_keywords and update_keyword.
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 a concrete usage pointer: 'Use search_locations and pass its location_key verbatim for city-level tracking.' This tells the agent the recommended prerequisite and workflow. However, it doesn't explicitly state when NOT to use this tool (e.g., vs update_keyword or bulk_update_keywords), though the verb 'add' semantically implies creation.
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 and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral insight beyond annotations by explaining the 'source' field's three possible values (explicit, derived, fallback), which clarifies how the data is computed rather than merely stored.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that conveys the resource, verb, scope, response fields, and semantic of the 'source' value. It's appropriately compact with no filler, though the enumeration of source values is slightly dense and could be structured more cleanly.
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 single-parameter read-only tool with 100% schema coverage and clear annotations, the description is largely complete. It explains the response semantics adequately. However, it doesn't note any pagination or mention what an empty/absent defaults response looks like, which is a minor gap for a tool this simple.
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 documents the sole project_id parameter fully, including its pattern. With only one parameter fully specified, the baseline is 3, but the description adds value by confirming the parameter selects the project whose defaults are being read, reinforcing the project-scoped nature without contradicting 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 uses specific verbs and resources ('Get the effective rank-check schedule and SERP market defaults for a project') and clearly distinguishes this read tool from the sibling update_project_defaults. It names the specific response elements (serp_depth, serp_stop_on_match, source) which makes the tool's purpose concrete and identifiable.
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 clearly indicates it reads defaults for a project and explains the 'source' field semantics (explicit/derived/fallback), giving useful context for when to consult this tool. However, it doesn't explicitly contrast against update_project_defaults or get_project, leaving the usage boundaries implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false (mutation possible), destructiveHint=false, and openWorldHint=true. The description meaningfully adds context beyond annotations: it requires API write scope, consumes the project's own paid DataForSEO account budget, caches results for 12 hours shared across API/UI, enforces one-seed-per-call, and introduces max_cost_cents as a best-effort guard. This is substantial behavioral disclosure that annotations couldn't convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description packs substantial information into ~90 words and is front-loaded with the critical 'Requires API write scope' and paid-account caveat. However, it's a wall of sentences without any structuring (headers, lists, separators), and several facts (12-hour cache, clickstream cost, already_tracked) are concatenated in a way that makes them easy to skim past. The density is high but organization is flat.
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?
This is a complex, cost-bearing, stateful tool with 9 parameters, no output schema, and non-trivial caching and pricing behavior. The description covers the key operational risks: cost estimation flow, per-call seed constraint, cache sharing, clickstream surcharge, and rate-card source. Gaps remain (no explanation of mode differences, no description of what results look like given no output schema), but for a stateful paid tool the essential context is well covered.
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 56%, and several params (mode, fresh, include_clickstream, result_limit) lack schema descriptions beyond enums/types. The description compensates for some gaps but not all. It clarifies already_tracked (marks tracked keywords), explains estimate_only as a free dry run, positions max_cost_cents as a best-effort guard, and flags clickstream cost implications. However, the fresh flag and result_limit semantics are not explained in either schema or description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens by stating it's 'Paid keyword research' using a provider account, and combined with the tool name 'research_keywords' and input schema (mode/seed/result_limit), the purpose is reasonably clear. However, it never uses a crisp verb+resource sentence like 'Research keyword suggestions for a seed term' — the actual action is implied through schema context rather than stated. It doesn't explicitly distinguish itself from siblings like get_keyword_metrics, add_keywords, or run_rank_check, though the cost-estimate framing partially differentiates it.
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?
This is excellent. It explicitly instructs when to use estimate_only first for cost control, warns 'Send one seed per call', explains caching behavior shared with API and UI, flags that clickstream doubles cost, and notes the rate card comes from get_provider_rates. Coupled with the required project_id and seed parameters, the agent has clear operational guidance on how and when to invoke this tool vs free 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?
Annotations only declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, which tells the agent this is a write operation but not destructive. The description clarifies it's a toggling operation and doesn't create/modify webhook endpoints, but doesn't disclose behavior details like idempotency semantics, partial vs full replace of unspecified channels, or confirmation behavior. For a write tool with minimal annotations, some additional behavioral context (e.g., what happens to unlisted channels) would help.
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, zero fluff. Each sentence earns its place: the first states the core function, the second clarifies scope boundaries and names alternatives. Highly front-loaded with the essential purpose in the first sentence.
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?
This is a moderately complex tool (12 boolean parameters across semantic categories) with no output schema and only 8% schema coverage. The description clarifies the webhook boundary well but does not explain the semantic grouping of parameters (alert vs check vs import vs invite), which is the main cognitive burden for the agent. Given the complexity and low coverage, more description would be warranted.
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 8% (only project_id has a description), with 12 parameters total. The description names the three channels (email, Slack, webhook) but the actual parameter list uses more granular naming (alert_email, check_email, import_email, invite_email, and corresponding _in_app variants). The description does not explain what alert/check/import/invite categories mean or how boolean false interacts with unspecified channels. Given very low coverage, the description should compensate more, so baseline 3 is generous.
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 tool's purpose: turning notification channels (email, Slack, webhook) on/off. The verb 'update' plus the resource 'notification preferences' and the specific behavior (channel switches) distinguish it from sibling tools like create_webhook/update_webhook.
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 states what it does NOT do ('does not create or change webhook endpoints') and directs the agent to the alternative tools (create_webhook/update_webhook). This is exemplary when/not/alternatives guidance, especially valuable given the large sibling list.
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: it discloses the snapshot_expired 409 behavior, the per-100-row provider rate, write-scope requirement, and the dependency on a prior analyze_backlinks call. However, the annotations already declare readOnlyHint=false (mutation implied) and it doesn't detail what happens to the snapshot after loading rows (does it expire? does it cache?), rate limits beyond the stated 100-row step, or whether this consumes provider budget in a way distinct from the initial analysis. Reasonable transparency but some gaps remain.
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, zero filler. Front-loaded with the critical scope requirement and prerequisite. Every clause earns its place — the auth note, the rate, the error condition, and the prerequisite are all essential behavioral facts. Excellent conciseness.
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 pagination/extension tool with 100% schema parameter coverage and no output schema, the description covers the essential state-dependency (snapshot must exist and be unexpired), the prerequisite call, the auth requirement, and the error path. It doesn't explain the return format, but no output schema exists to reference and the tool's purpose is straightforward. Slightly incomplete around rate/budget implications for the provider, but this is a solid, well-rounded description for a moderately simple extension 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 all 5 parameters are documented in the schema itself. The description adds context about the snapshot-matching requirement for target and target_scope params, which helps. However, the description doesn't independently elaborate on parameter meaning beyond what the schema already provides, so baseline 3 is appropriate given the 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?
Description uses a specific verb+resource ('extends the current unexpired backlinks snapshot at the per-100-row provider rate'), clearly distinguishing this pagination tool from siblings like analyze_backlinks (which creates the snapshot). Mentions the 409 snapshot_expired condition and explicitly directs to run analyze_backlinks first, further differentiating the workflow.
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 states the prerequisite (run analyze_backlinks first), the failure condition (409 snapshot_expired when no current snapshot), and the condition of use ('current unexpired backlinks snapshot'). The 'Requires API write scope' note is clear guidance. While it doesn't name alternative tools explicitly, it references analyze_backlinks as the necessary predecessor, giving strong usage direction.
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 destructiveHint=true and readOnlyHint=false, and the description reinforces this with 'cannot be undone' and 'immediate' effects. It adds meaningful context beyond annotations: the immediate and irreversible nature, plus the server-lockout consequence for the configured key. No contradiction between description and 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, front-loaded with the core action, and every clause earns its place. The warning about server lockout is critical and concise. No wasted words or redundant restatement of the title.
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 destructive tool with no output schema, the description covers the critical behavioral aspects: immediacy, irreversibility, and consequences. It doesn't mention return values, but for a revoke operation that's less critical than the warning content it does provide. The mutation-tool burden is well met by the warning guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, which is decent but not complete. The description defines key_id ('by key id') but adds nothing about project_id or idempotency_key beyond what the schema provides. The schema describes all three parameters adequately, and the description focuses on the key_id semantics, so it earns the baseline given moderate 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 it revokes an API key by key id, which is a specific verb+resource combination. It doesn't explicitly distinguish itself from sibling revoke tools (revoke_personal_token, revoke_team_invite, revoke_migration_token), but the pairing with list_api_keys and create_api_key makes the targeting reasonably clear.
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 states when to use — only after user confirms revocation — and gives a strong exclusion/warning: revoking the server's own key locks the server out. This is excellent guidance that prevents harmful misuse. It clearly signals this is a destructive, irreversible action requiring user confirmation.
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 give readOnlyHint=false (mutation) and destructiveHint=false, but the description adds substantial transparency beyond that: it warns about provider cost, explains the synchronous default behavior, describes the async alternative contract, and notes the approval-flow dependency on the client. It doesn't detail what happens on failure or quota exhaustion, but the key cost/approval behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and efficiently front-loads the core purpose before diving into caveats. Every sentence earns its place: purpose, cost/approval warning, and async behavior. Slightly dense single paragraph could benefit from separating the async guidance, but overall it's tight and well-ordered.
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 5 params, no output schema, and mutation semantics (readOnlyHint=false), this description is fairly complete. It covers the cost implication, approval requirement, sync/async contract, and references the polling tool. Gaps remain around idempotency_key semantics and the output/return format, but the important operational details are well covered.
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 60% — three params (async, idempotency_key, project_id base) lack descriptions. The description adds meaning for async (explains sync/async distinction and polling behavior), which goes beyond the schema. idempotency_key and project_id aren't described, but the async semantic explanation meaningfully compensates. Not a 5 since idempotency semantics in particular remain undocumented.
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 'Run a provider-backed rank check for one keyword', specifying the verb (run), resource (rank check), and scope (one keyword/provider-backed). It distinguishes from siblings like get_rank_check_result (polling) and get_rank_history (historical data). However, it doesn't explicitly name sibling alternatives, which keeps it from 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Requires write access and may incur provider cost. Ask for explicit user approval immediately before calling' — a clear prerequisite and safety note. It also explicitly explains when to set async versus sync ('Set async to true to enqueue... poll it with get_rank_check_result'), naming the follow-up tool for the async path.
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 convey readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: requires write scope, uses project's own DataForSEO account, caches keywords for 12 hours, has a max_cost_cents best-effort guard, and details the cost model. This goes well beyond the annotations. Slight gap: doesn't state what the response/return format looks like or error behavior when cost exceeds guard.
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?
All sentences earn their place and the description is information-dense without bloat. It's moderately long but every clause adds operational value. Could be slightly more front-loaded with the primary action stated first, but the structure is effective and 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?
For a 7-parameter tool with no output schema and only 71% schema coverage, this description is thorough: it covers auth requirements, cost model, batching limits, caching behavior, cost guards, and clickstream implications. It effectively compensates for the missing schema coverage on fresh and include_clickstream semantics. Sophisticated enough for an agent to make intelligent cost-aware decisions.
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 71% with 5 of 7 parameters described. The description adds meaning to max_cost_cents (best-effort guard), estimate_only (free dry run), include_clickstream (doubles cost, refines volumes), and fresh. This meaningfully augments what the schema provides, especially around cost semantics which is the tool's differentiator.
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 this tool fetches keyword metrics and costs money, with specific operational details. However, it doesn't use a crisp verb+resource framing (e.g., 'Fetch paid keyword metrics') and relies on the tool name for the basic action, though it does add substantial context about cost and caching that distinguishes its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Excellent guidance: tells the agent to call with estimate_only first when cost matters, documents pricing via get_provider_rates, explains the 700-keyword batch limit, 12-hour cache behavior, and how clickstream-refined volumes double cost. It explicitly names get_provider_rates as an alternative resource and gives clear decision heuristics around cost sensitivity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false, destructiveHint=false, so the mutation aspect is already implied. The description adds valuable behavioral detail: 'schedule is replaced as a whole: omitted schedule fields reset to their defaults (jitter 60, timezone UTC, no cron)' — this is a crucial side effect not visible in schema or annotations. This warning about destructive replacement goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all content-bearing. The first names the resources, the second warns about the destructive whole-replacement behavior, the third gives pairing/lookup guidance. No fluff. Could arguably be more compact but the density of information justifies the length.
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 11 params, no output schema, and moderate annotation support, the description covers the critical ambiguities: schedule replacement semantics, SERP market movement pairing, and lookup guidance. It doesn't fully document return values (no output schema exists) and doesn't enumerate each parameter, but covers the highest-risk behaviors. Reasonably complete for complexity.
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 only 45%, so the description must compensate. The description explains the semantics of the schedule fields (jitter default 60, timezone UTC, cron) and the pairing rule for country/device vs location_key. It clarifies the idempotency dimension, frequency enums, and location_key pattern. It doesn't document every parameter individually, but for 11 params with 45% coverage this meaningfully compensates.
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 states the specific verb+resource (update project default rank-check schedule and SERP market) and clearly differentiates from siblings like get_project_defaults (read counterpart), update_project (broader project settings), and search_locations (lookup helper). It names two distinct update areas and how to move the SERP market.
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?
Description explicitly instructs to provide country and device together OR use a location_key, and to use search_locations and pass its location_key verbatim — clear when-to-use guidance. It doesn't explicitly name alternatives/siblings or state when NOT to use this tool, but the usage context is clearly conveyed.
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 annotation destructiveHint=true already flags destructiveness, and the description adds meaningful context: it enumerates exactly what gets destroyed (keywords, rank history, settings) and emphasizes irreversibility ('This cannot be undone'). This goes beyond the annotation by specifying the full blast radius and requiring user confirmation.
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, zero waste. Every sentence earns its place: the first defines scope and consequences, the second sets the usage gate. Front-loaded with the primary verb and 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 destructive mutation with no output schema, the description covers the key context: what is destroyed, irreversibility, and user-confirmation requirement. The idempotency_key parameter is not described, and there's no mention of post-deletion state or error handling, but for a delete operation with the destructive annotation and clear scope, this is reasonably 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?
Schema description coverage is 50%, with project_id documented in the schema (including a pattern and pointer to list_projects) but idempotency_key undocumented in the schema. The description doesn't explain idempotency_key semantics. However, the description clarifies the destructive outcome tied to project_id, adding operational meaning. The undocumented idempotency_key is a minor gap given schema coverage of the key parameter.
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 'Permanently delete a project and all of its keywords, rank history, and settings.' It uses a specific verb (delete) with a specific resource (project) and enumerates the cascading scope, distinguishing it clearly from sibling deletion tools like delete_keyword, delete_saved_view, and delete_alert_rule, which operate on different resources.
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 'Use only after the user confirms deletion,' providing a clear precondition for safe usage. It doesn't name specific alternative tools, but given the large sibling list and the destructive nature, the confirmation requirement is the key usage gate. Exclusions/alternatives are not explicitly named, but the cascading scope makes the use case self-evident.
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 and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: newest-first ordering, cursor pagination behavior, and the fact that system sources are included in filtering. It doesn't describe return shape or rate limits, but with readOnly annotations that burden is lighter.
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 that pack all the essential info: purpose, ordering, filters, and pagination mechanism. Zero waste or repetition of what the schema already documents.
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 read-only listing tool with 71% schema coverage and good annotations, the description covers the important behavioral aspects (ordering, filters, pagination). It doesn't detail the return value format, but there's no output schema and this is a straightforward list operation, so a 4 is appropriate rather than a gap requiring higher effort.
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 71%, and most params have useful descriptions. The description adds value by explaining that 'source' includes system sources (giving concrete examples rank_tracker and search_analytics), and clarifies that 'type' is an exact match. This goes beyond what the schema enum/pattern alone conveys.
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?
Specific verb (list) + resource (signals for a project) + clear scope (newest first). Explicitly names the filter dimensions (source, type, date range) and pagination, distinguishing it from sibling tools like list_traffic_snapshots and list_triggered_alerts which list different signal-adjacent 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 states ordering (newest first) and clearly explains the filtering capabilities including source, type, and date range via from/to. It explains that source includes system sources such as rank_tracker or search_analytics, which is helpful. However, it doesn't explicitly name alternatives or state when NOT to use this tool versus list_traffic_snapshots or get_rank_history, though the scope is reasonably implied.
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 substantial behavioral context beyond the annotations: it discloses that cache misses require API write scope and spend the project's own DataForSEO budget, that snapshots are cached for 24 hours, and that aggregate views should be computed from rows and treated as 'within fetched rows' only. This is critical operational knowledge not conveyed by readOnlyHint=false. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and information-dense, packing multiple important behaviors into a few sentences. It's somewhat dense and front-loaded but every sentence adds new information relevant to correct usage. Slightly packed, but no 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?
For a complex 9-parameter tool with no output schema and no nested objects, the description covers the most critical operational aspects: budget spending, caching, scoping, cost control workflow, and data interpretation caveats. It lacks a bit of clarity on the exact output schema structure but the return valuation summary is addressed. Given the complexity, this is reasonably 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 input schema fully documents all 9 parameters. The description does add high-level guidance on estimate_only and max_cost_cents workflow, and clarifies the relationship between fresh and cache behavior, but most parameter semantics are already covered in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes backlinks and specifies what it returns: summary metrics, 12-month history, and per-link rows with new/lost status. It distinctively emphasizes the budget-consumption aspect, which sets it apart from sibling tools like get_cost_estimate or load_more_backlink_rows.
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?
Provides explicit usage guidance: call estimate_only first for a free dry run, then use max_cost_cents as a best-effort request guard. Also notes cache behavior (24-hour snapshots, fresh parameter to bypass). Differentiates between reading cached snapshots vs spending budget, though it doesn't explicitly name an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful context by explaining the two pricing structures (flat-priced per-check options vs plan-priced monthly plans) and the anonymous endpoint nature, which is valuable beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Front-loaded with the purpose, followed by useful explanatory detail about pricing models and the no-scope requirement. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param, read-only list endpoint with no output schema, the description explains what's returned (rate cards), the two pricing models, and the access model (anonymous). This is complete for the tool's simplicity level; no output schema means the return format responsibility is minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters and 100% coverage, the schema is trivially complete. The description establishes no parameters are needed ('Anonymous endpoint; no project scope needed'), which is the entire story for parameter semantics. This fully compensates for the zero-param case, warranting baseline 4 as per the rubric.
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 public provider rate cards used for rank-check cost estimates' with a specific verb, resource (rate cards), and purpose. It distinguishes between sibling tools by clarifying it's about cost-estimate rate cards and mentions 'Anonymous endpoint; no project scope needed' which differentiates it from get_cost_estimate and provider-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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when this applies (for rank-check cost estimates) and clarifies no project scope is needed, which helps the agent know there's no prerequisite. It implicitly distinguishes from get_cost_estimate by noting this lists rate cards rather than computing an estimate, though it doesn't explicitly name the alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable context about authentication ('Anonymous preflight endpoint; no project scope or credential needed') and specifies the exact information returned. This goes beyond the annotations and helps the agent understand side effects and requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise three-sentence paragraph. The first sentence states the core purpose and return values, the second clarifies access requirements, and the third provides a clear usage recommendation. Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is complete. It covers purpose, access prerequisites, and return data, and provides a recommended usage context. There are no gaps that would leave an agent confused about when or how to invoke this 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?
The tool has zero parameters, so the baseline score is 4. The description does not need to elaborate on parameter semantics, and it correctly focuses on behavioral and usage aspects. No parameter documentation is missing.
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 phrase 'Check whether a cloud export package can be imported' and clearly identifies the resource and the operation's purpose. It also names the exact return values (running app version, latest applied migration, accepted schema versions), distinguishing it from any sibling read-only 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 includes explicit guidance: 'Use before preparing a migration to confirm the export schema is still supported.' It also notes the endpoint is anonymous and requires no project scope, which clarifies the context of use. However, it does not mention any alternatives or when-not-to-use scenarios, so it stops short of a 5.
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:

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

Score Badge

Copy to your README.md:

[![bisibility-mcp MCP server](https://glama.ai/mcp/servers/CorgiCorner/bisibility-mcp/badges/score.svg)](https://glama.ai/mcp/servers/CorgiCorner/bisibility-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/CorgiCorner/bisibility-mcp'

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