Mencoro MCP server

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

Goes well beyond the annotations: it discloses the concrete side effects (clusters created, queries reassigned), the name lower-casing rule, and the collision behavior (an existing matching name is reused rather than duplicated). It also explains the retry safety mechanism via requestId, which is meaningful context given 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?

Four sentences, effectively front-loaded, with the primary effect stated first and safety/naming caveats after. Slightly dense but every clause carries distinct information; nothing is redundant with the annotations or schema.

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 non-idempotent mutation with no output schema, the description covers the lifecycle (propose via start_auto_clustering, preview via get_job, then apply), side effects, and retry semantics. It does not state whether the operation is reversible or what the call returns, which are the remaining minor gaps.

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, and it does for the most ambiguous parameter: requestId is explained as a fresh idempotency key to reuse only on retry. jobId is contextualized through the 'completed start_auto_clustering job' flow, though organizationId and projectId are left to the 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 precise verb and resource ('Apply the grouping a completed start_auto_clustering job proposed') and immediately enumerates the effects: creates named clusters and moves tracked queries. It is clearly distinguishable from start_auto_clustering (which proposes) and create_clusters (which it references for naming behavior).

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 precondition (a completed start_auto_clustering job), a workflow instruction ('Show the proposal (get_job) to the user first'), and explicitly routes naming behavior to create_clusters. The alternative tools in the same flow are named, so an agent knows when to reach for this versus them.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing non-obvious write semantics: names are stored lower-cased, must be unique per project, and any name that fails is reported in 'failed' without aborting the remaining creations. It also explains the idempotency-key retry contract, which annotations alone cannot 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 dense sentences, front-loaded with the core action and scope, followed by behavioral constraints and routing/retry guidance. No filler, though the sentence on name storage and failure handling packs several distinct facts together.

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 explains the partial-failure return shape ('failed') and the requestId retry contract for this mutation. It omits permission/auth prerequisites and what a successful response contains, but otherwise covers what an agent needs to invoke it correctly.

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% (only requestId is documented in-schema, and the description echoes the retry guidance rather than adding syntax). The description does add real meaning for 'names' (normalization, uniqueness, partial-failure behavior) and confirms the 100-item cap, but organizationId and projectId remain undocumented in both places.

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 up to 100 query clusters in a project') plus a definition of what a cluster is, and the scope constraints (max 100, unique lower-cased names). It is clearly distinguishable from siblings like start_auto_clustering and set_tracked_query_clusters, which are named explicitly.

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 two adjacent alternatives and their purposes ('Assign tracked queries with set_tracked_query_clusters, or let start_auto_clustering propose groups'), plus the retry protocol with requestId. It gives clear context for choosing this tool, though it doesn't state explicit exclusions (e.g., when not to create clusters manually).

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 it as a non-read-only, non-destructive, non-open-world write. The description goes beyond that by disclosing the persistent side effect ('from then on its mentions and rankings are tracked') and the retry/idempotency handling via requestId. It does not mention permission requirements, but the key behavioral traits are 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?

Two tight sentences with the core purpose front-loaded, followed by the discovery alternative and the idempotency note. No filler; each clause carries information. Slightly dense but well ordered.

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 create tool with no output schema, the description covers purpose, persistent effect, a related sibling, and retry semantics. Gaps remain around permissions and duplicate-handling, but nothing essential to correct invocation 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 only 17% (only requestId is documented inline), so the description must compensate. It adds meaning for websiteDomains ('its website domains'), brandNames ('the names it is mentioned by'), and requestId usage, but leaves organizationId, projectId, and name to the schema alone. 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+resource (add a competitor), the target scope (to a project), the inputs it carries (website domains, mention names), and the downstream effect (mentions and rankings tracked beside the brand's). This distinguishes it cleanly from discover_brands, update_competitor, and delete_competitor 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 names the alternative 'discover_brands can propose competitors', telling the agent where competitor candidates come from versus creating one directly. There is no explicit 'when not to use' or prerequisite statement, but the create-vs-discover distinction is clearly drawn.

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 already declare write/non-destructive/non-idempotent behavior, and the description adds genuinely non-obvious context beyond them: the requestId idempotency-key contract ('reuse it if you retry, so a retry never creates a second project') and the fact that competitor discovery has no dedicated tool. It does not cover permissions/organization scoping or what the call returns, so it falls short of 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?

Front-loaded with the core action in the first sentence, then workflow and idempotency guidance. It is a dense paragraph rather than a list, but each sentence carries distinct operational value (ordering, sibling names, retry semantics) with little redundancy.

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 not need to explain return values, and it covers the creation scope, required inputs at a high level, and the surrounding workflow. What is missing is what the caller gets back (e.g., a project id needed for the follow-up create_tracked_queries call), which an agent orchestrating the sequence would benefit from.

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 meaningfully compensates for the undocumented competitors parameter by explaining it needs both suggested names and websites, and clarifies that brandNames are the aliases a brand 'goes by'. The undocumented name and organizationId params remain unexplained, keeping this 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+resource ('Create a project that monitors a brand') and scopes exactly what the project contains: website domains, brand names, optional competitors. It also explicitly separates this from the sibling create_tracked_queries ('Tracked queries are added afterwards'), so an agent can route correctly 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?

Gives explicit sequencing and alternatives: propose everything to the user at once, pull brand names from suggest_brand_names, add tracked queries afterwards via create_tracked_queries, and use list_untracked_competitors after the first checks. It even notes the gap that no tool finds competitors, which prevents the agent from searching for a nonexistent sibling.

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 annotations, it discloses that each check spends budget, that skips are reported, and that a confirmationToken gate exists with a defined acquisition path. It also explains the requestId idempotency contract (fresh, reused only on retry), adding real operational context well beyond openWorldHint/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?

The paragraph is front-loaded with the core creation semantics before constraints and the confirmation workflow. It is dense and every clause carries information, though the single-block format could benefit from clearer separation of the multi-step workflow.

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 high-complexity mutation with 11 params, no output schema, and low schema coverage, the description is thorough: it covers creation semantics, budget cost, skip behavior, and the confirmation gate. It does not spell out the return payload (what 'reported' contains), a minor gap given no output schema.

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%, so the description must compensate, and it does for the key semantic parameters: queryTexts/engines/countries combination logic, checkFrequency scheduling, nPasses pass-count, and confirmationToken. It leaves queryClusterIds and the id parameters undocumented, so coverage is strong but not 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?

The description states a specific verb and resource ('Start tracking queries') and precisely defines the combinatorial semantics: 'every combination of queryTexts x engines x countries (at most 100) becomes a tracked query.' This clearly distinguishes it from siblings like update_tracked_queries, delete_tracked_queries, and create_clusters.

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 prerequisite workflow: call preview_operation first, show the plan to the user, and call this tool only after explicit agreement. It also names the exact alternative (preview_operation) with the argument needed and explains skip conditions (already-tracked combos, repeats, unsupported Google AI Mode countries).

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 already flag destructiveHint=true and idempotentHint=false, but the description adds substance beyond them: exactly what is destroyed (answers, matches, metrics history), that the operation is irreversible, and that a confirmationToken gate exists. This is precisely the context an agent needs before a destructive call.

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 with zero waste, ordered by importance: what is deleted, the safer alternative, then the mandatory confirmation step. 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?

Given no output schema and no annotation detail beyond the hints, the description covers the critical path for a destructive tool: scope, irreversibility, alternative, and the confirmation gate. It stops short of explaining requestId or the scoping role of organizationId/projectId, which leaves a minor completeness gap for a 5-parameter 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 0%, so the description must carry parameter meaning. It does well for two of five: it documents how to obtain confirmationToken (via preview_operation with tool "delete_tracked_queries") and implies the trackedQueryIds batch limit ("up to 100"). organizationId, projectId, and requestId remain unaddressed, leaving real gaps at this coverage level.

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 blast radius ("together with their captured answers, matches and metrics history") and the batch cap of 100. This clearly distinguishes it from update_tracked_queries and the other delete_* 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?

Explicitly names the alternative and the condition that should route an agent away from deletion: pause via update_tracked_queries if the goal is only to stop spending budget without losing history. It also spells out the mandatory confirmation workflow and the exact precondition (user must explicitly agree) before 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 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 readOnly/idempotent/non-destructive. The description adds genuinely useful behavior: it is UNFILTERED by ownership, only four AI engines yield citations, and date ranges are bounded by a retention window. It does not describe pagination or result shape beyond the per-source 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?

Front-loads the core purpose and the groupBy distinction, then layers scope caveats. The closing 'answers questions like...' sentence is somewhat redundant with the opening but is not wasteful enough to penalize heavily.

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 returned metrics (citation count, distinct answers, tracked queries, average rank), which an agent needs. Combined with the retention and engine caveats, it is nearly complete for an 8-param read tool, though pagination behavior remains unspecified.

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% across 8 params, so the description carries a real burden. It explains groupBy and what each source metric means, but groupBy/engines already have schema descriptions, and limit, offset, dateFrom, and dateTo go unexplained in both places. Partial compensation only.

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 (cited domains/pages) and distinguishes the two grouping modes (groupBy=domain vs page) in the first clause. It also clarifies the scope as sources of AI answers, setting it apart from sibling tools like get_mention_mix or get_share_of_voice_formula.

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 clear context: the list is unfiltered by ownership (brand/competitors/third-party), only AI engines produce citations, and dates must fall within retention. However, it names no alternative tool for filtered or non-citation views, so the when-not path is left implicit.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the return shape (one row per cluster) and the retention-window constraint on dates. It stops short of noting pagination or error behavior, but adds clear value over the annotations.

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

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

Front-loaded with the core purpose and return shape, followed by the constraint and example questions. It is slightly longer than necessary given the trailing example questions, but no sentence is wasted and structure is logical.

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 analytics tool with annotations covering safety and no output schema, the description usefully conveys the return granularity and the date constraint. However, with 8 parameters at 38% coverage and no output schema, the engines/countries/ungrouped-query filters remain undocumented, leaving an agent without guidance on several optional inputs.

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 38%, so the description must compensate. It clarifies the project scoping, date window, and cluster grouping (queryClusterIds), but leaves engines, countries, and includeUngroupedQueries unexplained in either place, so the compensation is only partial.

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 ('rank-tracking metrics broken down per keyword cluster') and even describes the output granularity ('one row per cluster with its positions, share of voice and sentiment'). The 'cluster' framing distinguishes it from the flat metrics siblings, but it never names or contrasts against get_sentiment_breakdown or get_rank_tracking_time_series, so differentiation is left to inference.

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 concrete context with example questions ('which keyword clusters are strongest or weakest') and states a precondition ('dates must fall within the data retention window'). However, it offers no explicit exclusions or named alternatives, so an agent must infer when to prefer it over the closely related breakdown/time-series siblings.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: output structure (per-competitor rows with win rate and average positions), the 'tracked competitors only' restriction, and the data-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 comparison logic, then output shape, then optional filter and constraints, ending with example questions. Dense but every clause carries information; the final example-questions sentence is slightly redundant but still useful for routing.

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 analytical tool with no output schema, the description is largely sufficient: it explains what the result rows contain, the competitorId focus, and key constraints. Minor gaps remain around the non-competitor filters and required identifiers, but nothing critical is missing for correct 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 43%, so the description must compensate but only partially does. It clarifies competitorId as the single-rival focus and adds a retention-window constraint on the date params, but says nothing about organizationId, projectId, or how engines/countries filter the comparison, leaving those to the 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 analytical operation: comparing who is named higher in AI answers where brand and competitor both appear, with a clear output shape (one row per competitor, win/loss/tie counts, win rate, representative query). This is precise enough for an agent to distinguish it from a generic share-of-voice or mention tool, though it does not explicitly name a sibling alternative.

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 clear usage context with example questions ("who wins when we both appear", "do I outrank competitor X", "who is mentioned first") and constraints (tracked competitors only, dates within retention window). It lacks explicit when-not guidance or named alternative tools, keeping it below the top tier.

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 adds genuinely new behavior: recommended polling cadence and the prohibition on restarting an in-flight job, plus the fact that the result only appears once completed.

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: the first states what is returned, the second states how to use it. No filler, front-loaded with the return semantics.

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 returns and does so (status, then result). Coverage of status values is partial (only 'completed'/'failed' named) and parameter identity is thin, but for a simple polling tool this is close to 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 0% and neither jobId nor organizationId is described in the schema. The description implicitly explains where jobId originates (from the starter tools) but says nothing about organizationId or the expected ID format, leaving a real gap for a 2-required-param tool.

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 (fetch a background job's status/result) and names exactly which sibling tools produce the jobs it reads. An agent can distinguish this from the discover_*/start_auto_clustering producers 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 operational guidance: poll every few seconds until status is 'completed' or 'failed', and do not restart the job while pending/running. Both the when-to-call and the when-not-to-act condition are stated.

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 already declare this a safe, idempotent read, so the bar is lower. The description still adds real behavioral context beyond structured fields: counts are raw per-pass rows, cited links are excluded, and results are not directly the share-of-voice inputs (which average passes and weight links). It does not describe return shape, but the caveats about counting semantics are genuinely useful.

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 operation and exclusions, then escalation to alternatives. Mostly earns its sentences, though 'Use to understand mention composition' is slightly redundant with the opening clause and the share-of-voice digression is dense.

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 and modest param coverage, the description does the heavy lifting: it defines exclusions, counting semantics, retention constraints, and routes to two sibling tools. An agent has enough to call it correctly, though the identity parameters remain undocumented.

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% across 6 params. The description partially compensates by stating dates must fall within the data retention window (a real constraint on dateFrom/dateTo) and by noting competitor/unrelated-brand exclusion, but organizationId, projectId, engines and countries carry no added meaning in the description beyond the schema's own notes and the get_available_filters pointer.

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 (brand's own AI text-mention counts), the grouping dimensions (type, tone, qualifier), the date window scope, and the exclusion rules for competitors and unrelated brands. An agent can distinguish this from get_share_of_voice_formula or get_sentiment_breakdown 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 alternatives explicitly and the conditions selecting them: get_sentiment_breakdown for the positive/neutral/negative split, get_mention_samples for the actual mention texts. It also frames the intent of the tool ('understand mention composition') and gives example questions, so when/when-not is fully resolved.

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 adds genuinely new behavioral context — 'Dates must fall within the data retention window' — plus the limit bounds, which annotations cannot express. It stops short of describing pagination/return shape, so a 4 rather than 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?

Front-loaded with what the tool returns, then alternatives, then constraints. Slightly dense with parenthetical asides, but every sentence carries real signal and 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 12-parameter read tool with no output schema, the description covers purpose, filter dimensions, limit bounds, retention constraint and sibling routing. Gaps remain around sort semantics and date format, but nothing critical to correct invocation 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 only 25%, so the description must compensate. It documents the limit range and names the filter dimensions (engine, sentiment, mention type, competitor), but says nothing about sortBy, offset, or date format, leaving several of the 12 parameters documented in neither place.

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 themselves, for qualitative review and verifying sentiment labels.' It explicitly distinguishes itself from siblings get_sentiment_breakdown and get_mention_mix, so an agent can select it without opening other 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?

Explicit routing: 'Use to READ individual mentions. For the aggregate sentiment split use get_sentiment_breakdown; for the brand's own mention counts by type, tone and qualifier use get_mention_mix.' It also states the retention-window constraint and the limit range, 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 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, and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the shape of the returned payload (counts and caller role), which annotations cannot express and which matters since no output schema exists.

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, no filler, with the returned-content summary front-loaded and the prerequisite stated second. The initial sentence is a noun fragment rather than a verb-led statement, which is slightly less crisp but costs nothing.

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 single-parameter getter with no output schema, the description covers what comes back and how to obtain the id. The remaining gap is sibling disambiguation against get_organization_overview, which the description never addresses.

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 the single organizationId is completely undocumented in the schema. The description compensates by explaining where the id comes from (retrieve it via list_projects), which is meaningful provenance an agent would otherwise lack. It still omits the id's format, so it is 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?

The description enumerates the specific resource and the exact fields returned (profile, status, caller's role, member/project/invitation counts), which is far more concrete than the title. It does not, however, differentiate this tool from the near-identically named sibling get_organization_overview, leaving the agent to guess which retrieval to pick.

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 workflow precondition, but it says nothing about when to choose this tool over get_organization_overview or list_members. It is a how-to-get-the-ID hint rather than genuine when-to-use guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine behavioral context: that this is a current-state snapshot with no date filtering, that it aggregates across all active projects, and that it includes an organization-level rollup row. It does not mention auth, rate limits, or pagination, but for a read-only snapshot call those are minor.

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 resource and its grain ('one row per brand'), followed by the constraint and the alternative. Dense but every clause carries information; the column list is long but useful, and the closing example question is 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 by enumerating the returned fields and the ranking plus org-level aggregate, and it states the temporal semantics. What is missing is any guidance on sourcing organizationId and the absence of pagination/volume expectations for a cross-project board.

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?

Only one parameter (organizationId) and schema description coverage is 0%, so nothing in the structured data explains it. The description hints that project ids come from this call but never clarifies what organizationId is or where to obtain it. Baseline 3 given the single flat parameter, with a real gap left unaddressed.

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 (organization-level brand rank-health board) with verb-like scoping ('latest-snapshot'), and enumerates the exact columns returned (share of voice, mention rate, avg position, positivity, tracked-query count) plus the org-level aggregate. It is clearly distinguished from the per-project siblings it names.

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 declares a negative constraint ('takes NO date window') and routes to the alternative for date-ranged comparison (get_project_rank_tracking_stats per project id). It also gives a concrete triggering question the tool answers, which pins down when to select 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 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, and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the retention-window restriction on dates and the fact that this is an aggregated, project-scoped rollup. It does not mention result size or pagination behavior.

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

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

Front-loaded with the core purpose and scoping, followed by the routing hint and constraints. The metric enumeration is long but each item is a genuine output category, not filler. Reads as tight prose with no redundant sentences.

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 compensates by naming the returned aggregates, which is a strength. However, for an 8-parameter tool at 38% schema coverage, the parameter semantics gap remains unaddressed, leaving the definition only partially 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 description coverage is low (38%) and the description adds almost no per-parameter meaning beyond the generic 'date window'. It never clarifies organizationId, projectId, queryClusterIds, includeUngroupedQueries, or countries, and the low-coverage schema leaves those under-documented. The metric list implies engines but does not explain the engines param.

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 and enumerates the exact aggregates returned (average positions, trends, share of voice, sentiment split, rates, 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 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 routing instruction ('prefer it before the per-cluster or time-series tools') gives clear positive guidance and names the alternatives. It also adds the constraint that dates must fall within the data retention window. It lacks an explicit 'when not to use' or fallback for out-of-window ranges, so it stops short of 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful behavior: 'Dates must fall within the data retention window', the per-row structure (one tracked query = single engine + country), and the sign convention (positive = improved), none of which is in the annotations.

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

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

The core function is front-loaded in the first sentence, and each subsequent sentence (row semantics, sort keys, retention constraint, example questions) earns its place. It is slightly dense but not padded or repetitive.

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 describes the return rows (current position/share/sentiment plus signed trend delta) and the retention constraint. For a 10-param tool it is largely complete, though it says nothing about the enum values for sortBy or the engines/countries filters beyond what the schema already carries.

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 40%, so the description must compensate, and it does for the crucial params: it defines the dateFrom/dateTo window relationship (current vs immediately preceding equal-length window) and the sort semantics ('sortOrder desc = top gainers, asc = top losers'). Pagination (limit/offset) and the ID params are left to the schema, keeping it from 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?

The description states a precise verb+resource+scope: 'Ranks a project's tracked queries by how much a metric changed between the given window and the immediately preceding window.' This clearly distinguishes it from sibling time-series tools (get_tracked_query_time_series, get_rank_tracking_time_series), which track one query over time rather than ranking movers across 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?

It gives concrete usage context via example questions ('which queries moved the most', 'my biggest gains and drops versus last period'), making the intended scenario obvious. It does not, however, name alternative tools or state explicit exclusions (e.g. when to prefer a time-series tool over this one), 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 the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description adds genuinely useful behavioral context beyond that: a data-retention constraint on the date range and a response-size tradeoff tied to granularity. It doesn't cover return shape or pagination, keeping it off 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?

Dense and front-loaded: the core purpose leads, followed by the size advice, retention constraint, and illustrative questions. Every sentence carries information, though the example-questions clause is a slight luxury.

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 tool with no output schema and only 40% schema coverage, the description is adequate but leaves notable gaps — several filtering parameters are undocumented here and in the schema. The safety profile is covered by annotations, but parameter-level completeness is not.

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% across 10 parameters, so the description is expected to compensate — but it only touches granularity (already an enum) and the optional competitor lines. The engines, countries, queryClusterIds, and includeUngroupedQueries parameters receive no added meaning in the description.

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 — 'Time series of rank-tracking metrics for a project across a date window' — and specifies the bucketing dimension. This cleanly distinguishes it from the sibling get_tracked_query_time_series (query-level) and the point-in-time get_project_rank_tracking_stats.

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 concrete usage context via example questions ('what changed in my AI visibility', 'share-of-voice trend split by engine') and a scoping rule ('Prefer weekly or monthly for long windows to keep the response compact'). It does not explicitly name alternatives to use instead for query-level or aggregate views, 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 declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds a real behavioral constraint beyond them: dates must fall within the data retention window. It does not disclose pagination or result-size behavior, keeping it short of 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?

Front-loads the returned payload, then alternatives, then the date constraint, then example questions. Every sentence carries distinct information with 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?

No output schema exists, but the description conveys the shape of the result (positive/neutral/negative split, per engine, per competitor) and the date constraint. Gaps remain on the four undocumented parameters and on what empty engines/countries arrays mean, but nothing essential to correct invocation 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 only 38% across 8 parameters; dateFrom/dateTo, organizationId and projectId have no schema descriptions. The description partially compensates by tying dates to the retention window and naming the per-engine/per-competitor dimensions, but it says nothing about engines, countries, queryClusterIds or includeUngroupedQueries defaults.

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 (sentiment split of the brand's AI mentions) and scopes it precisely to a date window, broken down per AI engine and per competitor. It also explicitly names the siblings it is not (get_mention_mix for counts, get_mention_samples for texts), so an agent can route correctly 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?

Explicitly gives when to use it ('tone/sentiment questions') plus two named alternatives with the exact conditions that select them: get_mention_mix for mention counts by type/tone/qualifier, get_mention_samples for raw texts. It even supplies example questions to anchor 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 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 declare this a safe, idempotent read, but the description adds genuinely non-obvious behavior: entitlements are populated only for owners and are null for other members, mirroring the web app. That permission-dependent output nuance is valuable context an agent could not derive from the schema or annotations.

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 with no filler, and the usage trigger is placed at the end where it reads naturally as a call-to-action. The opening sentence is a noun phrase rather than a verb-led statement, a minor structural weakness but not 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?

With no output schema, the description must carry the return-value burden, and it does: it enumerates the returned fields and explains the null-entitlements case. Only the organizationId parameter's semantics remain unspecified, which is a small residual gap for a single-key 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 0% and the single parameter (organizationId) is never explained in the description, so no format or sourcing guidance is added beyond the schema. With only one obvious required parameter the practical risk is low, keeping this at the baseline.

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 concrete resources returned — subscription, tracked-query count, projected monthly checks — so an agent knows exactly what this tool fetches, going beyond the bare tool name. It does not, however, explicitly distinguish itself from the similarly-named sibling get_organization_overview, leaving that discrimination to inference.

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 it before creating tracked queries or raising check frequency, to stay within the plan" gives an explicit trigger condition and motivation for calling the tool. It stops short of naming an alternative tool or stating when NOT to use it, so it lands just below the top tier.

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 only the generic safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true). The description adds substantial context beyond that: an invitation email is sent, duplicates silently create nothing (and report that), a confirmationToken must be obtained via preview_operation with a human-approval gate, and specific auth/role requirements apply.

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 tightly packed sentences, front-loaded with purpose and role options before the confirmation-token procedure and permission requirements. Every sentence carries operational content, though the security/permission clauses could be trimmed slightly.

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 handles that by noting what happens in the duplicate case ('creates nothing and says so'). Combined with the permission requirements and the mandatory preview/confirmation flow, an agent has what it needs to invoke correctly; only the return payload shape is 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 only 20% (requestId is the sole documented property), so the description must carry the load. It does: it explains email, enumerates the role enum values, explains the origin and purpose of confirmationToken, and identifies organizationId as scoped to the organization. It does not clarify the organizationId format or the requestId retry semantics beyond what the schema states, but coverage of the five parameters is strong.

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 ('Invite someone to the organization by email with a role'), names the allowed role values, and describes the acceptance flow and the duplicate-address no-op case. An agent can distinguish this from list_members, update_member, and cancel_invitation 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 prescribes the precondition workflow: call preview_operation with tool "invite_member" and these arguments, show the plan to the user, and call this tool only after explicit agreement. It also states the required permission (organization:manage) and role (owner), and notes the duplicate-address case where nothing is 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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds ordering behavior ('newest first by default') and the accepted date format, which is genuine context beyond the annotations, though it says nothing about pagination or result 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?

Three tight sentences with the resource description front-loaded, followed by filters and the alternative-tool note. No filler, though the field enumeration could be marginally tighter.

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 outlines what a record contains and how filtering/ordering works. It is close to complete for invocation, with pagination controls the main remaining 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 description coverage is 0% across 9 parameters, so the description must compensate and only partly does: it explains engine, trackedQueryId and date filtering plus the YYYY-MM-DD format and default sort direction. limit, offset, sortOrder asc and organizationId/projectId are left 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 ('AI answers captured for a project's tracked queries') and enumerates the returned fields (answer text, engine, capture time, cited sources). It also explicitly separates itself from aggregate tools, so an agent can distinguish it from siblings like get_mention_samples or get_query_movers 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?

Gives a clear usage condition ('read what an engine actually said') and an explicit exclusion ('for aggregates use the metric tools'). It does not name a specific sibling metric tool, so routing is directional rather than precise.

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 declare readOnly, idempotent and non-destructive, so safety is covered. The description's real contribution is the aggregation grain — one row per query text rolled up across engine and country variants — which is behavior the schema cannot express. Pagination behavior (limit/offset interplay) is left unstated.

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, no filler, with the row-grain definition front-loaded before the filter/sort capabilities. The first sentence packs a lot, but each 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?

No output schema exists, so the description must convey the shape of the result, and it does by enumerating the metrics (share of voice, positivity, mention/link/search/shopping positions). The main gap is pagination semantics for a list endpoint with limit/offset and a 100-row cap.

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 0% schema description coverage across 16 parameters, the description must carry the load, and it does for most: it maps engine, country, cluster, status, check frequency, passes and text filters, the sort options, and gives the date format (YYYY-MM-DD, inclusive). It omits limit, offset, includeUngroupedQueries, and the required organization/project identifiers.

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?

Names a specific resource (keyword listings) with precise granularity — one row per tracked query text aggregated across engine and country variants — and lists the metrics returned. The closing line 'The keyword-level view of a project' frames its scope. It does not explicitly distinguish itself from near-siblings like search_tracked_queries or get_tracked_query, so it stops short of a 5.

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 tells you what you can filter and sort by, which implies the intended usage, but never states when to choose this over search_tracked_queries, get_tracked_query, or list_clusters. Usage is inferred rather than prescribed.

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 credit here goes to what the description adds: an auth requirement (owners only), result ordering, and pending invitations only when requested. The id-vs-userId warning is a valuable gotcha beyond anything in the annotations.

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

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

Three compact, front-loaded sentences, each earning its place: the resource/ordering/fields, the permission constraint, and the id warning that prevents a real API misuse. 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 return-shape burden and does so (members with role and state, optionally invitations, oldest first), and it discloses the owners-only prerequisite. Pagination behavior for limit/offset is the only notable omission for a tool of this complexity.

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 compensates only partly: it explains includeInvitations ("optionally also its pending invitations") and the organizationId context, but is silent on limit and offset. Those are conventional pagination parameters, so the gap is modest rather than critical.

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 (members of an organization) plus ordering (oldest first) and returned fields (role, state). The closing note ties it to update_member by clarifying the id vs userId distinction, so an agent can place it among the member tools without ambiguity.

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 a clear permission/context condition for when this call is valid. It stops short of naming alternatives (e.g. invite_member for adding members), but the listing purpose is unambiguous and no exclusions are needed.

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 bar is lower. The description adds genuine context beyond that: the tool's output is a dependency for all other calls. It doesn't disclose pagination or ordering behavior, keeping it at 4.

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 with zero waste; the prerequisite instruction is front-loaded and every clause carries information the agent needs.

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 discloses the shape of what is returned (organizationId, projectId pairs). For a 0-param read tool this is 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?

Zero parameters, so the baseline is 4. There is nothing parameter-level to document and the description correctly focuses on output semantics instead.

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 (list) and resources (organizations and their active projects) with the scope narrowed to the caller's memberships. It is clearly distinguishable from single-entity siblings like get_organization and get_project, though it doesn't explicitly name a contrast case.

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?

"Call this FIRST" is an explicit sequencing instruction, and it explains why: the returned (organizationId, projectId) pairs are a prerequisite for every other tool. This is exactly the when-to-use guidance an agent needs.

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 a safe, idempotent, closed-world read, so the bar is lower; the description still adds real context by explaining what each kind's results contain (position/title/URL vs position/merchant/price) and that ordering is newest-first by default. It is silent on pagination mechanics and the limit ceiling, which would have added more.

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 compact sentences, front-loaded with what the tool returns, then the kind variants, then the filters and default ordering. No sentence is filler and nothing important is buried at the end.

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 list tool with no output schema and no schema descriptions, the description does most of the necessary work: it defines the resource, the kind variants and their payloads, and the filtering dimensions. The remaining gap is pagination and the organization/project scoping parameters, which an 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 description coverage is 0%, so the description has to carry the load. It covers kind (both enum branches explained), trackedQueryId, dateFrom/dateTo including the expected YYYY-MM-DD format, and the default of sortOrder. It leaves organizationId, projectId, limit and offset unexplained, including the 1-100 range and pagination intent.

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 precisely (captured search result pages for a project's tracked queries) and disambiguates the two kinds, 'serp' and 'shopping', spelling out the fields each returns. It is clearly distinct from siblings like list_ai_responses or list_keyword_listings, though the verb 'list' itself comes from the name rather than the description.

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 states the two filtering axes (one tracked query, or capture date as YYYY-MM-DD) and the default ordering, which implies how the tool is meant to be used. However, it gives no when-to-use guidance, no exclusions, and never names a sibling alternative, so usage is only implied.

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 genuinely new behavioral context: untracked brands 'count in no metric' until tracked, websites are not known here and must be confirmed with the user, and checks must have run first. These are real constraints an agent would otherwise not anticipate.

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 statement and the returned fields, followed by prerequisites and parameter defaults. The first sentence is long and list-heavy, but every clause carries information rather than 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 does the work of explaining the return shape (answer counts, tracked-query counts, frequency, average position, one naming query, last-seen date) plus sort order, prerequisites, and the unknown-website limitation. The only notable gap is the undocumented limit parameter, which is minor for a listing 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 29%, so the description has to carry more weight than it does. It explains dateFrom/dateTo as YYYY-MM-DD defaulting to the last 30 days, but says nothing about limit (the schema gives it no description at all), and engines/countries semantics are only covered inside the schema itself.

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: brands named in a project's AI answers that are not tracked as competitors, with a parenthetical definition of what counts as a brand. An agent can distinguish it from discover_brands and list_competitor-style 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?

Explicitly positions the tool as the place to find competitors worth adding 'with create_competitor' and states the prerequisite that checks must have run (with the note that first checks run immediately after project creation). It does not contrast against the related discover_brands or suggest_brand_names siblings, so routing among the discovery-family tools 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond the annotations by explaining the current missing-token state and why data reads fail until setup finishes. This aligns with and reinforces the annotation hints without contradicting them.

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

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

The description is two sentences with no filler. The primary purpose is front-loaded in the first sentence, and the second sentence provides essential context. Every word 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?