Mencoro MCP server

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare non-destructive, idempotent, closed-world behavior, and the description still adds real value: the 100-item cap, additive (non-exclusive) membership semantics, and partial-failure handling where failures land in a 'failed' field without aborting the rest. 'Safe to retry' reinforces idempotency with operational meaning. It stops short of saying whether the whole call fails atomically or how the 'failed' entries are shaped.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the core action and cap, then additive semantics, then failure behavior, then retry safety. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with annotations covering safety and no output schema, the description covers scope, cap, additivity, partial failure, and retry safety – enough to invoke correctly. The main remaining gap is that no parameter is described at 0% schema coverage, so an agent must infer which ID goes where.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning, and it does not name or explain organizationId, projectId, trackedQueryIds, or queryClusterIds, nor their ID formats or the requirement that queries and clusters belong to the given project/organization. It only vaguely gestures at 'tracked queries' and 'query clusters' and never notes that the 100 cap applies to each array independently.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Add ... tracked queries to ... query clusters') plus the batch ceiling, so the operation is unambiguous. It does not explicitly contrast with the sibling remove_tracked_queries_from_clusters, leaving the agent to infer the inverse relationship from the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus alternatives such as remove_tracked_queries_from_clusters, create_clusters, or apply_auto_clustering, nor any stated prerequisites (e.g. that clusters must already exist). The only usage-adjacent statement, 'Other cluster memberships are left alone,' describes effect rather than selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description offers highly specific behavioral context beyond the annotations, detailing naming conventions (lower-cased reuse), cluster handling logic (what remains in 'full_regroup' mode), and the limitations of the response (it only shows resulting clusters, not memberships removed).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is quite long, which detracting from conciseness. However, every sentence is packed with unique, high-value technical constraints, so its density is appropriate despite its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of cluster management, operational modes, and the necessity of idempotency, the description is remarkably complete. It covers the how, why, and when of using this complex mutation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Given that schema coverage is low (25%), the description provides vital semantic context. It specifies that `jobId` must belong to a *completed* job and details the required logic for the `requestId` to ensure idempotency on retry.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the purpose: applying a proposal from a completed auto-clustering job. It distinguishes itself by clarifying that it executes the job's proposed grouping, which is a more active process than just creating a cluster.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

This description provides excellent workflow guidance. It specifies usage based on operation modes ('full_regroup', 'fill_gaps', 'add_on_top') and gives a critical warning that the user must check the 'get_job' output first, preventing incorrect tool invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true and non-idempotent, but the description goes well beyond them: it details exactly what is destroyed or affected, that subscription cancellation is deferred to the end of the billing period, the required permissions ('organization:manage' and the owner role), and the mandatory confirmation-token flow. This is rich behavioral context that the annotations alone do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense but purposeful sentences, front-loaded with the operation's effects before stating the confirmation and permission requirements. Each sentence earns its place, though the middle confirmation-flow sentence is long and could be marginally tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the description supplies the effect list, auth requirements, and confirmation workflow an agent needs to invoke it safely. The only residual gap is not clarifying organizationId semantics, which is minor given the parameter is self-evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 33% – only requestId is documented in the schema. The description compensates well for confirmationToken by explaining how to obtain it (via preview_operation) and its gating role, but it says nothing about organizationId beyond the obvious. The description adds partial meaning over the schema but does not fully close the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Archive an organization') and then enumerates the concrete downstream effects (projects archived and stop being checked, invitations cancelled, subscription cancelled at period end). This clearly distinguishes it from sibling tools like archive_project, restore_organization, and update_organization.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prescribes the required workflow: call preview_operation first with these arguments, show the returned plan to the user, and only call this tool after explicit user agreement. It names the alternative/prerequisite tool and states the conditions for invocation, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds the crucial behavioral context the annotations cannot: what actually gets destroyed (query checking stops), the visibility consequence (removed from project list), and reversibility via restore_project. The confirmationToken requirement is a non-obvious gate for a destructive op.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and consequences, then the required workflow. Two dense sentences with no filler; every clause conveys actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent tool with no output schema and no annotation detail on effects, the description covers the full picture: what happens, the escape hatch (restore_project), and the mandatory confirmation flow. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry parameter meaning. It explains confirmationToken thoroughly, including how to obtain it, but projectId, organizationId, and requestId get no explanation beyond their self-evident names. Partial compensation warrants a moderate score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Archive a project') and enumerates concrete effects: tracked queries stop being checked and the project leaves the project list. It also names the sibling restore_project, so an agent can distinguish it from the inverse operation without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit precondition workflow: call preview_operation with tool 'archive_project' and these args, show the plan to the user, and only proceed after explicit agreement. This leaves nothing to inference about when and how to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the concrete consequence (invite link stops working), the mandatory confirmationToken gate via preview_operation, and the auth requirements — context the annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, each carrying operational weight: effect, id discovery, confirmation procedure, and permissions. The destructive consequence is front-loaded rather than buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the description covers effect, prerequisites, the required confirmation handshake, and authorization — everything an agent needs to invoke it correctly and safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25%, so the description must compensate: it explains that confirmationToken comes from preview_operation's returned plan and that invitationId is obtained from list_members/includeInvitations. requestId's idempotency semantics are covered by the schema; organizationId remains unexplained but is self-evident.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Cancel a pending invitation') and immediately gives the observable effect ('its link stops working'), which distinguishes it from siblings like archive_organization or delete_cluster that also remove things but in different ways.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: find ids via list_members with includeInvitations, and mandates the preview_operation confirmation flow before calling. It also states the required permission (organization:manage) and role (owner), naming both the precondition and the tool sequence.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations mark this destructive and non-idempotent, and the description adds substantive context beyond that: the mandatory confirmationToken/preview flow, the permission and owner-role requirements. This tells the agent how to sequence the call and what authority is needed, which is exactly the burden a destructive mutation must carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action and the allowed roles, then the id caveat, then the gating workflow. Every clause carries information, though the token-flow sentence is dense enough that it could be split for scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema and thin parameter coverage, the description covers the critical gaps: authorization, confirmation sequencing, and identifier source. It does not say whether the new role replaces the current one or whether constraints exist (e.g. demoting the last owner), which an agent would want before acting.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 20% (just requestId is documented), so the description must compensate, and it largely does: it defines memberId's provenance, lists the role enum values, and explains the purpose of confirmationToken. Only organizationId is left unexplained, which holds it below a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Give an organization member another role') and enumerates the exact target values (owner, manager, viewer). It also disambiguates the key identifier by pointing to list_members and explicitly ruling out the user id, which separates it from sibling tools like set_member_project_access and invite_member.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete pre-flight workflow: call preview_operation with tool "change_member_role", show the plan, and only proceed after explicit user agreement — an unusually clear when-to-call gate. It also states access prerequisites (organization:manage permission plus owner role). It does not name alternative siblings for adjacent operations, so it stops short of the full when/when-not/alternatives bar.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses behavior well beyond the annotations: names are stored lower-cased, must be unique per project, and failures are per-name and non-blocking ('reported in failed without stopping the rest'). It also explains the idempotency-key retry semantics, which is the key nuance given idempotentHint=false (repeats would otherwise duplicate).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action and limits, then behavioral caveats, then next steps. Dense but every clause carries information; the second sentence is long and could be split for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, it covers failure handling, normalization, limits, and retry guidance. It doesn't describe the overall response shape beyond the 'failed' field, leaving the success payload implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25%, but the description compensates by explaining the normalization and uniqueness rules that govern the names array and the retry semantics for requestId. organizationId and projectId remain undocumented, though they are conventional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Create), resource (query clusters), and scope (up to 100 per project), plus a plain-language gloss of what a cluster is. An agent can distinguish this from list_clusters, rename_cluster, and the auto-clustering siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Points to add_tracked_queries_to_clusters for populating clusters and start_auto_clustering as an alternative way to propose groups, and explains the retry contract for requestId. It doesn't explicitly say when to create manually versus using auto-clustering, but the follow-up paths are clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the safety profile (not read-only, not destructive, not idempotent); the description adds the important consequence that once added, mentions and rankings are tracked alongside the brand's ongoing — a durable side effect the agent would otherwise have to infer. The idempotency guidance (fresh requestId, reuse on retry) also adds operational context beyond the hints without contradicting idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core purpose and the tracking consequence before the sibling pointer and retry note. The requestId sentence slightly restates the schema's own description of that field, keeping it just short of maximal efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, durable effect, discovery alternative, and retry semantics for a 6-parameter mutation with no output schema. Missing is duplicate-handling behavior (what happens if the domain is already tracked) and any indication of the returned object, but the essential call decision information is present given annotations supply the safety profile.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 17% — only requestId is documented in the schema. The description compensates for two parameters by explaining websiteDomains and brandNames semantically, but leaves name, organizationId, and projectId entirely to inference, so it is partial rather than adequate compensation for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Add a competitor to a project") and immediately specifies the two payload concepts the caller must supply (website domains, mentioned names). It is clearly distinguishable from update_competitor, delete_competitor, and list_untracked_competitors, which is named separately as the discovery path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete routing rule: use list_untracked_competitors to see which AI-mentioned brands are not yet tracked, implying this tool is the follow-up action. It does not state exclusions (e.g., what to do if the competitor already exists, or when update_competitor is the right call instead), so it falls short of a full when/when-not treatment.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=false, idempotent=false); the description goes well beyond them by disclosing the required permission (organization:manage), the owner role, the tenant-scope restriction, and the mandatory two-step confirmation workflow. Contradiction check: the false idempotentHint is consistent with the schema's opt-in requestId idempotency key, not a conflict.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler, ordered purpose/scope → gating workflow → authorization, so the most decision-relevant information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because there is no output schema, the description could say what is returned (e.g., the new organization id) and could state that 'name' has no stated uniqueness/reserved-word constraints. Otherwise it covers permissions, scope, and the confirmation contract adequately for a 3-parameter creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33% (only requestId is documented), so the description has to carry weight — and it fully explains how confirmationToken is produced (via preview_operation) and why it is required. It leaves 'name' with no semantic guidance beyond the schema's maxLength, which is a residual gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a new organization') and adds ownership scope ('owned by the caller'), which cleanly separates it from the other create_* siblings (create_project, create_competitor, create_clusters) and from update_/archive_organization.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit preconditions and the exact routing rule: only with a connection not limited to one organization, and it must be preceded by preview_operation with tool "create_organization" plus the same arguments, with user agreement obtained first. An agent knows precisely when this tool is callable and what to call before it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the generic write profile; the description adds real behavioral context: the permission restriction that causes refusal, the requestId retry contract that prevents duplicate projects, and the fact that tracked queries are a separate later step. There is a mild tension with idempotentHint=false, but the description's idempotency is opt-in via requestId, so it does not contradict the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, and each following sentence carries non-redundant workflow or constraint information. It runs a bit long and ends with a terse fragment ("Refused to a member restricted to selected projects") that would read better fused with the preceding guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter creation tool with no output schema, the description covers intent, preconditions, sibling routing and retry safety well. The notable gap is what the call returns — presumably a project identifier the agent would need for the follow-up create_tracked_queries step.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50%, but the description compensates by explaining brandNames as the names the brand is mentioned by, websiteDomains as the brand's own domains, competitors as optional with their own sites and aliases, and requestId as a reused-on-retry key. Only organizationId and name remain unelaborated, which are self-evident.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Create a project") and immediately defines what the project contains: website domains, brand names, optional competitors. It also distinguishes itself from the nearest sibling by noting that tracked queries are added afterwards via create_tracked_queries, so an agent won't confuse it with create_organization or the query tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly sequences the workflow: gather brand names from suggest_brand_names, propose competitors yourself (noting no tool finds competitors), and use list_untracked_competitors after first checks. It also states a hard precondition (refused for members restricted to selected projects) and retry behavior, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond annotations: discloses budget spend per check, the 100-combination cap, duplicate/skip behavior with reporting, and the confirmation-token gate. The idempotentHint=false annotation plus the requestId retry instruction is complementary rather than contradictory, though it could state more explicitly whether reuse of requestId with changed args is rejected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core semantics, then skip rules, then the confirmation workflow — logical ordering with no filler. Sentences are dense and long, but each carries load-bearing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nontrivial mutating, cost-incurring operation with no output schema, the description covers the creation semantics, cost implications, skip/report behavior, and the safety workflow. Remaining gaps (locale, queryClusterIds, project scoping) are secondary but real for an 11-parameter call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 36% across 11 params, and the description compensates for the important ones: it defines queryTexts/engines/countries as a cross-product with a 100 cap, ties nPasses and checkFrequency to checking behavior and budget, and explains confirmationToken and requestId. It says nothing about locale, queryClusterIds, or organizationId/projectId, leaving a meaningful gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Start tracking queries: every combination of queryTexts x engines x countries (at most 100) becomes a tracked query" states a specific verb, resource, and the exact construction semantics. An agent can distinguish this from add_tracked_queries_to_clusters or preview_operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit prerequisite chain is spelled out: call preview_operation with this tool name and arguments, show the plan and cost to the user, call only after explicit agreement. It also names what is skipped, so the agent knows when combinations will not be created.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, but the description adds value beyond them: the exact side effect on tracked queries (they leave the cluster but are not deleted), the irreversibility of the action, and the mandatory confirmation-token workflow with a user-agreement gate. That is meaningful behavioral context an annotation cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action and its blast radius, then the irreversibility warning, then the prerequisite procedure. No filler, and the ordering matches the order in which an agent needs the information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the description covers the safety-critical elements: irreversibility, side effects, and the required confirmation flow. The only gap is that the optional requestId parameter is never mentioned, which is minor but leaves one field undocumented everywhere.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so all five parameters rest on their names alone. The description compensates for the most hazardous one by explaining what confirmationToken is and how to obtain it, but organizationId, projectId, clusterId, and especially the optional requestId are left entirely unexplained. Partial, but not full, compensation for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ('Delete a query cluster'), and the second immediately disambiguates the scope from the sibling delete_tracked_queries by clarifying that tracked queries survive. An agent can distinguish it from archive_project, delete_competitor, and delete_tracked_queries without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when-and-how: call preview_operation with tool "delete_cluster" and these arguments, show the returned plan to the user, and only then call this tool after explicit user agreement. The alternative path (preview_operation) and the gating condition are both named, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it enumerates the cascading deletions (mentions, search results, shopping results) and states 'Irreversible.' It also discloses the confirmationToken authorization gate, which the annotations do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: action+scope first, destructive/irreversible warning second, required workflow third. Front-loaded and free of filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with no output schema this covers the essentials: cascade scope, irreversibility, and the token gate. The only notable omission is any explanation of requestId — with idempotentHint=false, an agent cannot tell whether retrying with the same requestId is safe or a no-op.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 5 parameters, so the schema itself contributes no semantics. The description explains confirmationToken's origin and purpose well, but organizationId, projectId, competitorId and requestId are left entirely unexplained — requestId in particular is not tied to the idempotentHint=false annotation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('Remove a competitor from a project') and immediately scopes the blast radius ('together with every mention, search result and shopping result'). This distinguishes it cleanly from update_competitor and from the other delete_* siblings without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit, ordered prerequisite workflow: call preview_operation with tool "delete_competitor", show the returned plan to the user, and only call this tool after explicit user agreement. This is exactly the when/how guidance an agent needs and it is stated as a hard requirement, not a suggestion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, but the description adds what annotations cannot: which related data is destroyed (answers, matches, metrics history), that the action is irreversible, the 100-query batch ceiling, and a mandatory two-step confirmationToken protocol. That is substantial context beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what is destroyed and the irreversibility warning, then the safer alternative, then the confirmation procedure. Every clause carries operational weight; nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive batch tool with no output schema, the description covers blast radius, reversibility, batch limits, the safer alternative, and the exact prerequisite call sequence. An agent has everything needed to invoke it safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the burden. It usefully explains the non-obvious confirmationToken (obtained from preview_operation with the same arguments) and reflects the 100-item maxItems on trackedQueryIds, but organizationId, projectId and requestId are never mentioned, leaving gaps the schema cannot fill.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (delete tracked queries) plus the scope of collateral removal (captured answers, matches, metrics history) and the 100-item cap. An agent can tell immediately this is not the softer sibling pause_tracked_queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use pause_tracked_queries when the goal is to stop spending budget without losing history, and use this tool only after preview_operation plus explicit user agreement. Both the alternative and the required pre-call choreography are spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only mark it non-read-only, open-world and non-idempotent; the description adds the async background-job model, the mandatory polling step, and the crucial replacement semantics ('passing the full list including the names already there'), which prevents an agent from dropping existing aliases. It also discloses what shoppingEnabled and country actually change about the search.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense paragraph, front-loaded with what the job finds and immediately followed by the exclusion and the follow-up flow. Every clause earns its place, though the trailing shoppingEnabled/country sentence could be split for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex async job with no output schema and sparse parameter documentation, the description covers everything an agent needs: what is produced, how to retrieve it, how to present it, and how to persist it without clobbering existing data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 20%, so the description must carry the load and largely does: it explains shoppingEnabled (adds Google Shopping), country (narrows to one market, ISO 3166-1 alpha-2), and the competitorId used downstream. requestId's idempotency semantics come from the schema itself, and organizationId/projectId are self-evident, so the gap is minor.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Start a background job that finds other names the project's brand and each of its existing competitors go by in AI answers and search results (aliases, product and store names).' It also draws an explicit boundary — 'It does not find new competitors' — which separates it from siblings like create_competitor and discover_keywords.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit end-to-end workflow: poll get_job for the result, show it to the user, then add chosen names with update_project (brand) or update_competitor (competitor, by competitorId). The 'does not find new competitors' exclusion plus the named follow-up tools leave nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the non-destructive, non-idempotent, open-world profile, and the description adds value beyond them: it discloses the asynchronous background-job nature, the need to poll get_job, and the subscription precondition. It stops short of describing job lifetime, rate limits, or expected runtime.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: the action first, then the exclusion parameter, then the end-to-end workflow. Every sentence carries distinct information with no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an async mutation tool with no output schema, the description correctly redirects to get_job for results and names the follow-up tool for committing results, which is the essential context. Minor gaps remain around the undocumented country/language parameters and job timing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is very low (14%), so the description must compensate. It explains input (seed can be a topic, product, or URL) and excludeQueries semantics ('leaves out ones already tracked'), but says nothing about country, language, or how organizationId/projectId scope the job.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Start a background job that proposes search keywords for a project from a seed') and clarifies the seed forms (topic, product, URL). It is clearly separable from siblings discover_brands, discover_prompts, and create_tracked_queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Lays out the full workflow: start the job, poll get_job for results, review with the user, then track with create_tracked_queries. It also names the preconditions (excludeQueries for already-tracked queries, active subscription requirement), leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds meaningful context beyond annotations: this is asynchronous (a background job requiring polling via get_job) and gated on an active subscription. It does not explain the requestId idempotency contract, hence not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense paragraph of three sentences with no filler; the async/polling instruction is front-loaded after the purpose. It is efficient, though packing purpose, param note, workflow and prerequisite into a single block is slightly heavy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly explains the downstream handoff (get_job → create_tracked_queries) and the subscription gate, which covers the async lifecycle. However, for a 7-parameter tool at 14% schema coverage, it leaves most parameter semantics and the expected format of 'input'/results unexplained, so it is only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 14% (only requestId is documented in the schema), so the description carries the burden and largely fails: it explains only excludeQueries ('leaves out ones already tracked'). The meaning and format of input, country, language, organizationId and projectId are left entirely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource with scope: 'Start a background job that proposes the questions people ask AI assistants about a topic in one country - the prompts worth tracking on AI engines.' An agent can distinguish this from discover_keywords and discover_brands from the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives the full operational path: poll get_job for the result, review with the user, then call create_tracked_queries, plus the prerequisite 'Requires an active subscription.' It names the successor tools explicitly and leaves no inference about when to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this as a safe, read-only, idempotent operation. The description adds important behavior beyond annotations: the exact return shapes for engines/countries ({code, label}) versus clusters/competitors ({id, name}), and the critical rule to pass 'code'/'id' — never the label/name — to other tools' parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the discovery purpose, followed by concrete return-shape examples and a direct usage instruction. Every sentence earns its place with no wasted wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a discovery tool with no output schema, the description supplies the return structure and the key rule for consuming values, which is strong. Its main gap is that it does not document the two required identifiers, though the annotations already cover the safety profile.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and neither required parameter (organizationId, projectId) is described in the schema. The description only indirectly implies a project context and does not mention organizationId at all, so it fails to compensate for the missing parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Discover') and resource ('engines, countries, keyword clusters and competitors configured on a project'), clearly stating what the tool returns. It is distinguishable from all sibling tools, which are CRUD or metric tools rather than filter-discovery tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context for when to use the tool: 'so subsequent metric tools can be called with valid filter values' and 'Call this before filtering.' However, it does not name alternatives or state when not to use it, so it stops short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description correctly spends its space on non-obvious behavior: results are UNFILTERED by ownership, only AI engines produce citations (so google_serp/google_shopping yield nothing), and retention limits the date window. It also enumerates the per-source metrics returned, which no structured field provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first clause, followed by the returned metrics, the ownership caveat, and the engine constraint. It is a dense paragraph but nearly every sentence carries information; only the trailing example question feels slightly redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates well by naming the fields returned per source (citation count, distinct answers, tracked queries, average rank). With 8 parameters at 25% schema coverage, the gaps are the pagination parameters, but the rest of what an agent needs to call this correctly is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25%, so the description does useful work by explaining the two groupBy modes and reinforcing that only AI engines carry citations. However, limit and offset — the pagination controls — are never mentioned in description or schema, and the four required IDs get no framing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource — the domains or pages most cited across a project's AI answers in a date window — and immediately clarifies the groupBy switch that determines whether it returns domains or pages. The 'sources the answer engines drew on' framing makes it clearly distinct from siblings like list_ai_responses or get_mention_samples.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context with the concrete example question ('which websites and pages does the AI cite or quote for me versus competitors') and notes the prerequisite that dates must fall inside the retention window. What's missing is an explicit routing statement versus a near-neighbor sibling, and 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description focuses on adding context: the retention-window constraint on dates and the shape of the result (one row per cluster with named metrics), which matters since there is no output schema. It does not discuss pagination, empty-result behavior for the cluster/ungrouped combinations, or cost of wide date ranges, so it is not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the metric grain and then the constraint and usage examples; nothing is padding. The second example question is somewhat redundant with the first, keeping it just short of tightest possible form.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter read tool with no output schema, the description does well to describe the result rows, but it leaves the empty-list defaults for engines and countries unexplained and offers no routing to sibling tools. An agent can call it, but must infer default filter semantics from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

At 50% schema coverage, the schema documents engines, countries, queryClusterIds and the subtle includeUngroupedQueries semantics, while organizationId, projectId and both dates are bare. The description reinforces the date window and its retention constraint but says nothing about the required identifiers or what an empty engines/countries array means (presumably all), leaving the coverage gap partly unaddressed. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: rank-tracking metrics broken down per keyword cluster, with the exact output grain (one row per cluster) and the metrics included (positions, share of voice, sentiment). That grain-plus-metrics phrasing clearly separates it from sibling breakdowns such as get_sentiment_breakdown or get_rank_tracking_time_series without needing to open a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The example questions ("which keyword clusters are strongest or weakest", "how does my niche compare to my generic queries") give concrete contexts that map directly to this tool. It also states the date-retention prerequisite. It stops short of naming alternatives or exclusions, e.g. when to prefer get_project_rank_tracking_stats or list_clusters instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds real behavior: the answers subset is restricted to co-mentions, output is one row per tracked competitor, only tracked competitors are included, and dates must fall within the retention window. It stops short of describing ordering, row count limits, or what happens when there are zero co-mentions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The defining constraint (both mentioned, who ranks higher) is front-loaded, followed by the row shape and then optional narrowing. The output-field enumeration in the middle sentence is a bit list-like, but every clause carries information an agent needs to interpret the result.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully spells out the return columns (co-appearance counts, win/loss/tie splits, win rate, average positions, representative query). It also flags the retention-window and tracked-competitor preconditions. Remaining gaps are minor: sort order, empty-result behavior, and response size are unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 43%, and the description only enriches two parameters: competitorId (focus on a single rival) and the date range (must be inside the retention window). The four ID/date parameters are self-evident, and engines/countries already carry their own schema descriptions, so this is adequate but not compensating for the uncovered fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states the exact operation: comparing best mention position for answers where brand and competitor both appear, and the row granularity is explicit ('one row per tracked competitor'). It enumerates the returned metrics, which cleanly separates it from siblings like get_share_of_voice_formula or get_rank_tracking_time_series.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is stated through concrete example questions ('who wins when we both appear', 'do I outrank competitor X') plus the population constraint 'For the AI answers where the brand and a competitor are BOTH mentioned'. It also notes the optional single-competitor narrowing. What's missing is any explicit routing to alternative tools when the user wants overall share rather than head-to-head.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations only declare readOnly/idempotent/non-destructive; the description adds genuinely new behavioral context: expected latency (about 15 minutes, timeout near 30), the timeout code, and the full enumeration of error.code values with the note that error.message prescribes next steps. That is exactly the operational detail a polling client needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what is returned, then polling guidance, then timing, then error shape. Four tight sentences, each carrying distinct operational information with no restatement of the name or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates well by describing the status/result/error payload shapes. The remaining gap is parameter identification (which id goes where), the only thing an agent could still get wrong.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% — neither jobId nor organizationId has any documentation, and the description never mentions either parameter or clarifies that jobId must be the id returned by the producing job. With no schema-level help, the description should compensate but does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (a background job) and what is returned (status, then result), and names the exact sibling tools that create such jobs (discover_brands, suggest_brand_names, discover_keywords, discover_prompts, start_auto_clustering). This lets an agent place the tool precisely in the workflow without consulting the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit polling cadence (every few seconds), explicit stop conditions (status completed or failed), and an explicit prohibition (do not start the job again while pending or running). That is when-to-use, when-to-stop, and what-not-to-do in one place.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive and closed-world behavior. The description adds genuinely new context: no account data is touched and no sign-in is required, which tells the agent this is a safe public read with no auth prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, followed by a necessary topic inventory and the calling convention. The long topic list is dense but earns its place as a routing aid; there is little wasted prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single optional, well-documented parameter and no output schema, the description is complete: it says what the tool returns (guide content on the named topics), the calling convention, and the auth posture. Nothing an agent needs is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents both the enum values and the omit/'index' convention. The description's topic enumeration largely restates the enum and repeats the index workflow, adding only light framing about what each topic contains.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (answer questions) and resource (the public Mencoro guide), and enumerates the exact subject matter covered. It is clearly distinguishable from the data-fetching siblings, which return account/project data rather than documentation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prescribes the call pattern: omit the topic for the index, then call with the topic that answers the question. It also states the tool needs no account and works unauthenticated. It does not, however, acknowledge overlapping siblings such as get_metric_glossary or get_share_of_voice_formula, which also answer definitional questions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the read-only/safe profile, yet the description adds genuinely non-obvious behavior: counts are raw per-pass rows, cited links are excluded, and the numbers therefore differ from share-of-voice inputs which average per-pass and weight links. It also flags the data retention constraint on dates. That is exactly the kind of caveat an agent could not infer from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Scope and grouping are front-loaded, and the sibling routing follows immediately. Minor waste: 'Use to understand mention composition' restates the opening, and the example-question sentence is optional garnish, but nothing is confusing or out of order.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does convey the return shape (counts grouped by type, tone and qualifier, raw per-pass) and the caveat that they are not share-of-voice inputs. What remains thin is the identifier/date parameter contract, which neither schema nor description covers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 33%: engines and countries are documented in the schema, but organizationId, projectId, dateFrom and dateTo carry no descriptions. The description only partially compensates — it says dates must fall within the retention window but never states the date string format or what the identifiers represent. Enough to be usable, not enough to be complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('AI text-mention counts ... grouped by type, tone and qualifier') with explicit scope: the project brand only, competitors and unrelated brands excluded. An agent can distinguish it from get_sentiment_breakdown, get_mention_samples and the share-of-voice tools on the strength of the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names two concrete alternatives and the condition selecting each ('For the positive/neutral/negative sentiment split use get_sentiment_breakdown; to read the actual mention texts use get_mention_samples'). It also states a negative case — this is not the tool for share-of-voice inputs — and gives example questions that pin down the intended use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds substantive context beyond that: the data-retention window constraint on dates, the pagination model, and the 1-50/default-20 limit. It stops short of describing sort semantics or how paging via offset interacts with new data arriving.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences with the core purpose front-loaded and alternatives after. No filler, though the closing 'Answers questions like...' sentence is somewhat redundant with the opening.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 12 parameters, no output schema, and 25% schema coverage, gaps remain: how to page with offset, what each sortBy option means, and how countries filtering interacts with the date range are all unexplained. Adequate for routing, incomplete for confident invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 25%, so the description must carry weight; it does explain the limit range/default and the filters (engine, sentiment, mention type, competitor), but leaves sortBy, offset, countries, and the date format/semantics undocumented in both places. Partial compensation for a low-coverage schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'paginated sample of the raw AI mention texts' — and explicitly contrasts it with get_sentiment_breakdown (aggregate split) and get_mention_mix (counts by type/tone/qualifier). An agent can pick the right tool without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'use to READ individual mentions' plus two named alternatives with the conditions that select each. It also frames the answerable question ('show or export the actual AI mention texts'), which anchors intent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: 'Static reference; no project data,' which tells the agent results are constant and not tenant-specific, plus an outline of the returned fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: the mapping purpose and routing trigger come first, the return shape second, and the static nature last. Nothing is padded or redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully enumerates what each entry contains, which is exactly what the agent needs. The only gap is the unexplained required organizationId, which is minor given the reference nature of the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has one required parameter (organizationId) with 0% schema description coverage, and the description never mentions it. This is a notable omission for a tool described as a static, project-data-free reference — the agent gets no explanation of why an org id is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb and resource — 'Map a plain-language or unfamiliar request to the right Mencoro metric and tool' — and immediately names the artifact it returns (each metric with synonyms, unit, range, direction, tool, example questions). This clearly separates it from data-fetching siblings like get_project or get_tracked_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit, condition-based trigger: 'Call this first when a request is vague, non-technical, phrased in another language, or uses wording that does not match a tool name.' That is strong usage guidance, but it never juxtaposes this against near-neighbor reference/discovery tools such as get_mencoro_guide or get_available_filters, so the agent must infer which reference to pick.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered. The description adds real value beyond them by disclosing the returned data shape (counts of active members, pending invitations, and accessible projects), which matters because no output schema exists. It stops short of saying whether counts are live or cached, or whether any permission is needed to read another org.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One long run-on sentence chained with multiple "and ... and" clauses, which obscures the primary object (the organization profile) behind a trailing list of counts. The prerequisite hint is a separate, useful sentence, but the first sentence should have been front-loaded with the verb and split.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does a fair job of naming the returned fields, which is the main completeness requirement here. It is still missing sibling disambiguation (notably get_organization_overview) and any note on error behavior for an unknown or inaccessible organizationId.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single required parameter, so the description must carry the burden — and it does partially by telling the agent to obtain organizationId via list_projects. It does not state the expected format (UUID vs. slug vs. name), which is the remaining ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description enumerates exactly what the tool returns: org profile, status, caller's role, active member and pending invitation counts, and accessible project count. That is specific and resource-focused, though it is a noun-phrase list rather than a verb+resource statement, and it never distinguishes itself from sibling get_organization_overview, which sounds like it covers similar ground.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use list_projects first to find the organizationId" gives a concrete prerequisite for obtaining the required ID, which is genuinely actionable. However, there is no guidance on when to pick this tool over get_organization_overview, get_project, or list_members, so the usage decision against siblings is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real context the annotations cannot: it is a current-state snapshot with no date parameter, it is implicitly scoped to projects the caller can access, and output is ranked one-row-per-brand with an org aggregate. It stops short of covering result limits, pagination, or behavior when the organization has no active projects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core snapshot/one-row-per-brand framing before the metric enumeration and the alternative-tool guidance. The first sentence is dense and long, but the parenthetical metric list is load-bearing given there is no output schema; only the trailing example question is arguably surplus.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must describe the return shape, and it does: one row per brand with named metrics, an organization-level aggregate, and ranking order. Combined with the explicit no-date-window constraint and the pointer to per-project tools for time series, an agent has everything needed to call it and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With one obvious identifier parameter and 0% schema description coverage, the description carries some burden; it clarifies the scope semantics indirectly ("active projects the caller can access in an organization"), which tells the agent that organizationId governs the row set. However, it never says what an organizationId looks like, how to obtain one, or what happens if the caller lacks access, so it doesn't fully compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — a "latest-snapshot rank-health board across the active projects the caller can access" — and enumerates exactly what a row contains (share of voice, mention rate, average mention position, positivity, tracked-query counts per engine family) plus the organization-level aggregate. The scope (one row per brand, ranked by share of voice) is precise enough to distinguish it from per-project siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when NOT to use it ("takes NO date window") and names the alternative path with a concrete sibling ("call the per-project tools (e.g. get_project_rank_tracking_stats) for each project id returned here"). It even supplies a sample question it answers, leaving no ambiguity about selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered elsewhere. The description adds that the payload includes domains, brand names and competitors with ids, but says nothing about auth requirements, error behavior, or scoping beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with no filler, though it is structured as an output summary rather than leading with the action the tool performs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully enumerates the return payload (name, status, domains, brands, competitors with ids), which partially fills that gap. But it omits any guidance on the two required identifiers and doesn't clarify scoping or possible empty results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% — both required parameters (organizationId, projectId) are undocumented in the schema, and the description never mentions them or distinguishes their roles. With low coverage the description should compensate, and it does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description is a noun phrase enumerating returned fields rather than an explicit verb+resource statement, though 'Get a project' in the title plus the field list make the retrieval purpose inferable. It does distinguish itself from list_projects by describing the detail payload rather than a collection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance versus siblings like list_projects. However, the parenthetical that update_competitor and delete_competitor take the returned competitor ids is an implied usage context, telling the agent this tool supplies ids for later mutations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered; the description adds the retention-window constraint, which is real behavioral guidance not present in annotations. It also discloses the returned metric families, which matters since there is no output schema. It stops short of describing aggregation semantics (e.g. how averages are weighted across engines/countries).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three front-loaded sentences: what it returns, when to prefer it, and what questions it answers. The metric inventory is long but informative rather than redundant; the only mild waste is the somewhat run-on enumeration in sentence one.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, read-only aggregation tool with no output schema and no nested objects, the description supplies the essential missing pieces: what data comes back and the retention constraint on the date range. Remaining gaps (aggregation/weighting behavior, how empty filters default) are secondary for a query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% — engines, countries, queryClusterIds and includeUngroupedQueries are documented in the schema, while dateFrom/dateTo, organizationId and projectId carry no field descriptions. The description only partially compensates, adding the date-window/retention constraint but nothing about the scope-control parameters (clusters, ungrouped queries, country/engine filtering).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (aggregated rank-tracking summary for a project) plus a concrete inventory of what it aggregates: positions, trends, share of voice, sentiment, mention/SERP/shopping rates, distribution buckets. It explicitly positions itself against siblings ('the project overview; prefer it before the per-cluster or time-series tools'), so an agent can distinguish it from get_cluster_breakdown and get_rank_tracking_time_series without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternatives and the ordering condition ('prefer it before the per-cluster or time-series tools'), and anchors usage in concrete user questions ('how visible is my brand', 'am I ahead of competitors'). It also states a hard precondition — dates must fall within the data retention window — which prevents a predictable failure mode.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the preceding-window comparison, the sign convention (positive = improved), the per-row grain (one engine + country), and the retention-window constraint on dates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core rank-definition in the first sentence, then row shape, sort semantics, and constraints. The final question examples are slightly redundant but still earn their place by anchoring usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description responsibly sketches the returned row (position/share/sentiment plus signed delta). It also covers window semantics and retention limits. Only pagination behavior (limit max 50, offset) is unaddressed for a 10-param tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 40%, but the description supplies meaning for the two enum-bearing params (sortBy = which trend delta to rank by; sortOrder desc/asc = gainers/losers). It says nothing about limit/offset pagination or the date parameter format, leaving several of the 10 params to the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (ranks) and resource (tracked queries) and precisely defines the comparison basis: change between the given window and the immediately preceding window of equal length. This clearly distinguishes it from sibling time-series tools like get_tracked_query_time_series.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames the questions it answers ("which queries moved the most", "biggest gains and drops versus last period") and explains how sortBy/sortOrder select gainers vs losers. No sibling alternative is named, so it stops short of a full when-not routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety bar is pre-cleared. The description adds genuine behavior beyond them: the retention-window constraint on dates, and the response-size implication of picking coarse granularity. It does not say what metrics the series carries or how the lines are keyed, which would be the remaining disclosure gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what the tool returns, followed by the performance heuristic, then the retention constraint, then intent-matching examples — a sensible ordering with little filler. The example-question sentence is slightly loose but earns its place by anchoring intent recognition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, no-output-schema tool with only 50% coverage, the description leaves notable gaps: it never says which rank-tracking metrics are returned (rank position? visibility? share of voice?) or how the series and optional competitor lines are labeled, so an agent cannot anticipate the shape of the response. What it does cover — windowing, bucketing, competitor and engine splits — is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% across 10 params, so the description must add meaning, and it does for granularity ('daily, weekly or monthly' plus a selection heuristic) and competitorIds ('per-competitor lines') and engines ('split by engine'). It says nothing about `queryClusterIds`, `countries`, or `includeUngroupedQueries` beyond the schema text, so it partially compensates rather than fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — a time series of rank-tracking metrics for a project, bucketed by granularity — which is concrete enough to act on. It implicitly separates itself from the query-level sibling (`get_tracked_query_time_series`) by scoping to 'a project', but never names that sibling, so the differentiation is inferential rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Offers real usage context: prefer weekly/monthly for long windows, dates must fall inside the retention window, and example questions ('what changed in my AI visibility', 'share-of-voice trend split by engine') that map intent to this tool. It stops short of naming alternatives or exclusions — nothing says when to reach for `get_project_rank_tracking_stats` or `get_tracked_query_time_series` instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low. The description adds real context beyond them: the date window must fall inside the data retention window (a failure mode an agent would otherwise hit), and the output is broken down per engine and per competitor. It does not describe pagination or response size limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the output shape, then alternatives, then the retention caveat, then examples. Slightly redundant to give both the 'tone/sentiment questions' cue and two example questions, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter read-only analytics tool with no output schema, this covers what the tool returns (sentiment split per engine/competitor), when to reach for it, and a key data constraint. A hint about default filtering when dimension arrays are empty would close the last gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%; the description adds one meaningful constraint for the date parameters ('Dates must fall within the data retention window') but says nothing about how engines, countries, queryClusterIds or includeUngroupedQueries shape the result — the latter's semantics live only in the schema. Adequate, not compensatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+breakdown dimensions: 'Positive/neutral/negative sentiment split of the brand's AI mentions over a date window, per AI engine and per competitor.' An agent can distinguish this from get_mention_mix and get_mention_samples without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit use case ('Use for tone/sentiment questions'), names two alternatives with the conditions that select them ('For the brand's own mention counts by type, tone and qualifier use get_mention_mix; to read the actual mention texts use get_mention_samples'), and adds concrete example questions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds the notable scoping nuance that the data is global yet requires a project context, though it leaves the tension between those two facts unresolved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences with the core content (what the constants are) front-loaded. No filler, though the final scoping sentence could be sharpened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only, two-parameter tool this is close to adequate, but with no output schema and no parameter docs, the unexplained global-vs-project scoping is a real gap an agent would need resolved before calling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning. It only obliquely touches projectId via "global (not project-specific), but scoped to a project you can access" and never explains organizationId at all, leaving both required parameters effectively undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource — the per-mention-type base weights and tone/qualifier multipliers behind the share-of-voice score — so the agent knows what comes back. It is fairly close to the sibling get_metric_glossary, but naming the concrete constants gives it some differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use this to explain how the share-of-voice metric is derived" implies usage, but never contrasts it with the near-identical sibling get_metric_glossary, nor states when it should be preferred or skipped. No prerequisites or exclusions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description's enumeration of returned fields adds value, but says nothing about scoping requirements or behavior when the id is unknown/unauthorized.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the tool's purpose and the field list appended compactly. The trailing 'Find ids with search_tracked_queries' is useful rather than filler. Minor run-on list of fields, but nothing wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only fetch with no output schema, listing the returned fields is a genuine substitute for a return-value spec. However, the zero-coverage parameters and absence of scoping/error context leave the agent with gaps it must guess at.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the three required parameters (organizationId, projectId, trackedQueryId) are bare strings. The description only implicitly references trackedQueryId via the reference to search_tracked_queries and never explains the org/project scoping requirement, so it fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('One tracked query's settings') and enumerates what the record contains (text, engine, country, status, check frequency, clusters, last check). It partially distinguishes itself by noting ids come from search_tracked_queries, though it doesn't contrast with get_tracked_query_matches or get_tracked_query_time_series.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tells the agent how to obtain the required id ('Find ids with search_tracked_queries'), which is the key prerequisite for calling this tool. It gives no explicit when-not guidance or mention of the time-series/matches siblings, 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the description usefully spends its budget on behavior instead: default sort order (newest first), date format (YYYY-MM-DD), and the default retention-window span for dates. That is genuine added context beyond the structured fields, though pagination/return-shape behavior is unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with what the tool returns before the kind breakdown and date defaults. No filler; slightly dense but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter read tool with no output schema, the definition covers the non-obvious semantics (kind, dates, default ordering). The main gap is pagination guidance around limit/offset, which the agent must infer from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and there are 9 parameters, so the description carries the burden. It compensates well for the ambiguous ones — the enum values of `kind` are explained concretely, and the date format plus defaults for dateFrom/dateTo are given. It says nothing about limit, offset, or the ID parameters, but those are self-evident.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (individual results behind one tracked query's metrics) and disambiguates the two result kinds — mentions in AI answers vs domain rankings in SERPs. This clearly separates it from aggregate siblings like get_tracked_query_time_series, though it never names those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied — drill down into the raw events behind a query's metrics — but there is no explicit when-to-use or when-not guidance relative to alternatives such as get_mention_samples, get_cited_sources, or list_ai_responses. The agent must infer the routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds real context: the data-retention date bound, the granularity trade-off, and that engine/country are implicitly fixed by the tracked query rather than exposed as parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then prerequisites, then advice and an example. Every sentence carries information, though the parenthetical granularity list and the example question add slight length without new constraint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, read-only time-series tool with no output schema, the description supplies the necessary routing, scoping, and constraint context. Minor gaps remain on date format and the organizationId/projectId semantics that an agent would need for an unambiguous first call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 29%, so the description must compensate, and it does for the important parameters: trackedQueryId's source, the granularity enum meaning, competitorIds' purpose (per-competitor lines, though the exact source hint lives in the schema), and the retention bound on dateFrom/dateTo. It leaves date string format and organizationId/projectId unaddressed, so not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'Time series of rank-tracking metrics for ONE tracked query across a date window, bucketed by granularity.' The scope word 'ONE' and the enumeration of granularity snapshots distinguish it clearly from the batch-oriented get_rank_tracking_time_series sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing ('Use search_tracked_queries to find a trackedQueryId'), usage advice ('Prefer weekly or monthly for long windows'), a hard constraint ('Dates must fall within the data retention window'), and a concrete example question, so the agent knows when and how to call it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuinely useful behavioral context: it is a current-state snapshot with no date window, and never-checked/overdue counts are scoped only to active queries. It doesn't discuss pagination or response shape, but the safety and scoping profile is well covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the concrete return contents before any framing, which is good. The trailing list of three example question clusters restates the same 'stale/overdue' idea three times and could be trimmed, but overall it stays tight and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so: it lists every count returned plus the overdue sample. Combined with the snapshot/no-date-window note, an agent has everything needed to select and invoke it correctly given its two simple required params.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for both parameters. The description doesn't document organizationId or projectId directly, but the phrase 'a project's tracked queries' implies the projectId scope, and both parameter names are self-explanatory. It neither compensates fully nor leaves the agent confused.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (a project's tracked queries) and enumerates exactly what it returns: total, active, paused, never-checked and overdue counts plus a sample. This level of specificity clearly distinguishes it from sibling tools like get_project_rank_tracking_stats or get_tracked_query_time_series, which cover different dimensions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit triggering questions ('what is stale or not being monitored', 'which queries are overdue, paused, or never checked') and clarifies scope with 'This is a current-state snapshot and takes no date window', implicitly steering the agent away from time-series siblings. It does not, however, name a concrete alternative tool to prefer in adjacent scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them by disclosing conditional nullability: entitlements are null for non-owners, and for members restricted to selected projects the plan, billing cycle, check budget, consumption and deactivation reason are all null. This is non-obvious, role-dependent behavior that an agent would otherwise misread as missing data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, all carrying load: the return contents first, then the two nullability conditions, then the usage condition. The opening sentence is long and stacked, but the most important information (what you get back) is front-loaded and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return values, and it does so at a reasonable level of detail including the role-conditional nulls. It stops short of describing the shape of the counts/projections or the deactivation-reason semantics, but nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description says nothing about organizationId. The parameter name is self-explanatory and it is the only input, so the risk is low, but the description does not compensate for the coverage gap by saying where the organizationId comes from or what form it takes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource and enumerates the exact contents: subscription, tracked-query count, projected monthly checks, and entitlements. It is clearly a read of plan/usage state, distinguishable from get_organization and get_organization_overview by the billing/limit framing. It opens with a noun phrase rather than a verb, so the operation is implied rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to call it 'before creating tracked queries or raising check frequency, to stay within the plan', which gives a concrete triggering condition. It does not name a sibling alternative or state when not to use it, but the use case is unambiguous for a read-only plan lookup.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the standard annotations, the description provides critical behavioral requirements, specifically noting the required permissions ('organization:manage' and 'owner role') and the state change behavior for existing members.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The tool definition is highly dense but extremely efficient. Every sentence contributes critical operational or workflow information without unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of roles, project scoping, and the necessary pre-invocation workflow, the description covers every major complexity point, making it highly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant semantic value beyond the schema, especially for the `projectAccess` parameter. It clarifies that these projects are defined only for when the invitee accepts and details a crucial constraint: an owner invitation cannot include project selection.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action and the outcome: 'Invite someone to the organization by email.' It is unambiguous about the tool's function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage guidelines are explicit and procedural. It mandates a specific workflow (call `preview_operation` first), defines the required user agreement, and handles the edge case where the email address already exists.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive, so the safety profile is covered. The description adds useful behavior: 'newest first by default', the filter dimensions, and the format of returned records, which goes beyond the annotations. Pagination behavior (limit/offset) is left unstated, so it isn't fully complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool returns, then filters, then the use-vs-aggregates routing. Three sentences, all substantive, with no filler. Slightly dense but every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with annotations covering safety and no output schema, the description covers returned contents, filtering, and default ordering well. Missing only pagination semantics and the obvious required IDs, so it is nearly complete without being exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry parameter meaning, and it does explain the key filtering params: engine filtering, single tracked query, and date range with the YYYY-MM-DD format plus default sort order. It does not mention limit/offset or the required organizationId/projectId, leaving some of the 9 params unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('list the AI answers captured for a project's tracked queries') and enumerates the returned fields (answer text, engine, capture time, cited sources). It also differentiates scope from the aggregate metric tools, so an agent can tell it apart from siblings like get_mention_mix or get_sentiment_breakdown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use it 'to read what an engine actually said' and to use 'the metric tools' for aggregates, giving a clear selection rule. It offers no named alternatives and no explicit when-not conditions, keeping it just below a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds useful context by specifying the return shape (names with ids), but says nothing about pagination behavior despite limit/offset existing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with the resource front-loaded and the parenthetical definition earning its place. No filler, though it could have used the freed space for parameter or pagination detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 undocumented parameters, no output schema, and pagination/ordering parameters present, the description is too thin for correct invocation. It partially offsets the missing output schema by naming the returned fields, but leaves the request side almost entirely unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 5 parameters, so the description carries the burden and fails to compensate. It mentions only the project scope implicitly and says nothing about limit, offset, sortOrder, or organizationId semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States the resource precisely (a project's query clusters) and even defines what a cluster is, plus the returned fields (names and ids). It is clearly distinguishable from siblings like get_cluster_breakdown or create_clusters, though it never uses an explicit verb like 'list' to frame the operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no mention of alternative tools such as get_cluster_breakdown or search_tracked_queries. The agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds genuinely non-obvious behavior: a variant not checked in the range contributes its latest earlier position, and carriedPositions discloses which figures were carried and from when. The inclusive date-range semantics are also spelled out. Missing only pagination/truncation behavior for the result set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the row grain and metrics, then the carried-position edge case, then filtering/sorting, then a one-line scope framing. Nearly every clause carries information; density is high but no sentence is wasted. Could be marginally tighter around the metric list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 16 parameters, no output schema, and near-zero schema descriptions, the description does the heavy lifting: it defines the return grain, metric set, date-range semantics, carry-forward behavior, and filter/sort dimensions. The remaining gap is result-set size and pagination behavior, which matters for a list tool with a default limit of 20.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 6%, so the description must compensate; it does so partially by mapping "filter by engine, country, cluster, status, check frequency, passes or text; sort by any metric" onto the corresponding parameters. However, pagination (limit default 20 / max 100, offset) and the meaning of individual filter values go unaddressed, leaving several of the 16 parameters with no prose support.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the exact grain ("one row per tracked query text across all its engine and country variants") and enumerates the metrics returned, so an agent knows precisely what this returns. It also positions itself with "The keyword-level view of a project," which sets it apart from cluster- or snapshot-level siblings. It stops short of naming the specific alternative (search_tracked_queries, get_tracked_query_time_series) that an agent should choose instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: "The keyword-level view of a project" hints at scope, and the filter/sort listing implies the intended query pattern. There is no explicit statement of when to prefer this over sibling tools such as search_tracked_queries or get_cluster_breakdown, and no exclusions or prerequisites given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly/idempotent/non-destructive, and the description adds real context on top: an authorization requirement (owners only), the deterministic ordering (oldest first), and the critical id-vs-userId distinction that will silently break downstream mutations if missed. It does not describe pagination behavior or what the invitation entries look like, keeping it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with zero filler. The core behavior and the permission gate come first, and the cross-tool id caveat is placed last where it is most actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description steps in by naming the returned fields and ordering, and the owners-only note plus the id warning cover the two things most likely to cause a wrong call. Only pagination and the shape of the invitation records are left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the burden; it clarifies includeInvitations ("optionally also its pending invitations") and treats organizationId implicitly as the target org. The limit and offset parameters are never mentioned, leaving pagination semantics (page size cap of 100, default of 20) entirely to the schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource (an organization's members), the returned fields (role, state), the sort order (oldest first), and the optional extra (pending invitations), which is enough to separate it from get_organization or invite_member. It is written as a noun phrase rather than a verb+resource, but the listing intent is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Owners only, as in the web app" gives an explicit caller-permission gate, and the closing sentence routes the agent to change_member_role / suspend_member / reactivate_member by telling it which identifier those tools consume. It stops short of contrasting with sibling read tools such as get_organization, so there is no explicit when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuinely new context — the cross-tool dependency that its output is a prerequisite for other calls — plus a hint at the return shape (organizationId, projectId pairs). It stops short of describing pagination or what happens when the caller has no organizations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both load-bearing. The scope statement comes first and the critical 'call this FIRST' directive second, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining what comes back, and it names the key returned fields and their purpose. It is complete enough for an agent to know when and why to call it, though it omits edge cases such as an empty membership list.