Mencoro

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

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description adds genuinely new behavioral detail: per-item partial failure is reported in 'failed' without aborting the batch, other memberships are untouched, and the call is retry-safe. It does not cover auth/permission requirements or rate limits, so it stops 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?

Four short sentences, front-loaded with the operation and its limits, then failure semantics and retry safety. No filler or restatement of the title; every sentence carries information an 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 an output schema present, return values need no explanation, and the description covers the key behavioral risks for a batch mutation (partial failure, non-destructive additive semantics, idempotency). It is only slightly short of complete, omitting what happens with unknown cluster or query IDs and how org/project scoping constrains the operation.

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 all four required parameters. The description semantically identifies two of them (tracked queries, query clusters) and clarifies the many-to-many relationship, which is useful, but organizationId and projectId scoping go unexplained and the '100' limit merely restates the schema's maxItems constraint.

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 (add) and resource (tracked queries to query clusters) plus the cardinality ceiling of 100 and the many-to-many scope ('one or more query clusters'). This is unambiguously distinguishable from siblings like remove_tracked_queries_from_clusters, create_clusters, and delete_cluster 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?

The additive note 'Other cluster memberships are left alone' implies this tool is for augmenting existing cluster membership rather than reassigning it, and 'Safe to retry' hints it can be re-run. However, it never names an alternative or states when-not to use it (e.g. versus create_clusters or apply_auto_clustering), leaving the routing decision 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?

Beyond the annotations (which flag destructiveHint=true and idempotentHint=false), the description discloses mode-specific semantics ('full_regroup' removes memberships from other clusters; 'fill_gaps'/'add_on_top' only add), that nothing is deleted, that cluster names are lower-cased and existing names are reused, and that the response omits removed memberships. It also explains the requestId retry contract, which reconciles with the non-idempotent hint.

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, but every sentence carries load: mode semantics, non-deletion, naming rules, response shape, and the retry/idempotency contract. It is front-loaded with the core action, though the length is near the limit for one paragraph.

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

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

For a mutation tool with an output schema, the description covers everything an agent needs: the workflow prerequisite, per-mode effects, non-destructive guarantees, naming behavior, and the idempotency-key contract. Return values are summarized sufficiently without duplicating the 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 25%, so the description must compensate. It adds real meaning for jobId (a completed start_auto_clustering job) and requestId ('fresh... reuse it if you retry'), but organizationId and projectId are left entirely undocumented in both schema and description. Partial compensation merits a middle 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?

The description states a specific verb and resource ('Apply the grouping a completed start_auto_clustering job proposed') and immediately names the sibling tools involved (start_auto_clustering, get_job). Its scope is clearly distinct from siblings like create_clusters, add_tracked_queries_to_clusters, and start_auto_clustering.

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 workflow context: this tool consumes the output of a completed start_auto_clustering job, and 'show the proposal (get_job) to the user first' tells the agent the required preceding step. It does not explicitly state when not to use it versus manually adding queries to clusters via add_tracked_queries_to_clusters, so it falls 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 mark the tool as destructive and non-idempotent, but the description adds substantial behavioral detail beyond them: the exact cascading effects on projects, invitations, and subscription billing. It also discloses the required authorization level and the mandatory preview/confirmation protocol.

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 front-loaded with the core action and its consequences, then moves to prerequisites and permissions. It is dense but every sentence carries necessary information, with no filler.

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

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

For a destructive organization-level mutation with an output schema present, the description covers the critical missing context: cascade effects, authorization requirements, and the confirmation-token workflow. Return values need not be explained because an output schema exists.

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%, so the description must compensate. It explains the confirmationToken's origin and required use, but organizationId is left to the obvious parameter name and the requestId semantics remain in 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?

The description states a specific verb and resource (archive an organization) and goes further by spelling out the cascade: projects archived, pending invitations cancelled, and subscription cancelled at billing period end. This is clearly distinguishable from sibling tools such as archive_project and restore_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?

It gives an explicit prerequisite workflow: call preview_operation first with the same tool name and arguments, show the plan to the user, and only call this tool after explicit agreement. It also names the required permission and owner role, leaving little ambiguity 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 flag destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it names exactly what is destroyed (tracking of all queries, list visibility), states it is reversible via restore_project, and discloses the mandatory preview/confirmation gate. This is rich behavioral context beyond the safety flags.

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, then consequence, then the required workflow across two dense sentences with no filler. A small number of words do double duty (the confirmation flow), and nothing is repeated from the title or annotations.

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?

An output schema exists, so return values need no explanation, and the description covers purpose, blast radius, reversibility, and the mandatory confirmation sequence. The only shortfall is that two schema parameters (requestId especially) receive no coverage at 0% schema description coverage.

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

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

Schema description coverage is 0%, so the description carries the load. It thoroughly explains confirmationToken — where it comes from and how to obtain it — which is the highest-risk parameter. projectId and organizationId are self-evident by name, though requestId is not addressed at all, leaving one minor gap at 0% schema coverage.

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 immediately describes the concrete consequence: tracked queries stop being checked and the project disappears from the list. It also names the inverse sibling, restore_project, making the direction of the operation unambiguous against the many other project-mutating 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?

Gives an explicit prerequisite workflow: call preview_operation with tool "archive_project" and these arguments, show the returned plan to the user, then call only after explicit user agreement. It also contrasts with restore_project and specifies a required confirmationToken, 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?

The description adds substantial context beyond the annotations: the confirmationToken requirement, the preview_operation gating flow, the required permission and role, and the observable effect on the invitation link. What it does not cover – whether the invitation can be reinstated, rate limits, or post-cancel audit behavior – is minor for a single-item cancel. Well above the bar set by the destructiveHint annotation.

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

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

Three dense sentences, front-loaded with the action and its effect, then id discovery, then the required confirmation procedure. No filler, and each clause carries operational value for a destructive tool.

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 this is a destructive, multi-step-confirmation operation with an output schema that handles return values, the description covers the critical missing pieces: the confirmation gate, the permission requirement, and how to source the id. Fully adequate for correct invocation, though it could note idempotency guidance for the optional requestId.

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), so the description must compensate. It successfully explains confirmationToken's workflow role and where to find invitationId, but says nothing about organizationId or the idempotency semantics of requestId beyond what the schema already states.

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 ('Cancel a pending invitation') and immediately clarifies the consequence ('its link stops working'). This distinguishes it clearly from siblings like invite_member or update_member, and an agent knows exactly what effect to expect.

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 tells the agent how to obtain the required id ('Find ids with list_members and includeInvitations') and prescribes the pre-execution workflow ('call preview_operation ... show the returned plan ... call this tool only after the user explicitly agrees'). Prerequisites (organization:manage permission, owner role) are also stated, 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 destructiveHint=true and readOnlyHint=false, and the description reinforces this with concrete preconditions: a mandatory confirmationToken, an explicit user-approval gate, and the permission and owner-role requirements. This is real behavioral context beyond the annotation flags.

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, each carrying load — role options, identifier source, then the confirmation/permission workflow. Front-loaded with purpose, though the confirmation sequence is long enough that it slightly crowds the opening.

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

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

With an output schema present, return values need not be described; the description instead covers the things structured fields cannot — the preview/confirm protocol, permissions, and identifier semantics. An agent has everything needed to invoke this 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 coverage is only 20%, so the description must compensate: it clarifies that memberId comes from list_members rather than being a user id, lists the role enum, and explains the confirmationToken's purpose and how to obtain it. organizationId is left implicit, and requestId is already documented in 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 verb ('give ... another role'), the resource (organization member), and enumerates the three role values. It also disambiguates the target identifier from a sibling concept (user id), so an agent knows exactly what it does.

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 describes the required workflow: call preview_operation with tool 'change_member_role' and these arguments, show the plan, and only call this tool after the user agrees. It also names the permission (organization:manage) and the required caller role (owner), 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 non-readOnly and non-destructive, and the description adds real behavior beyond them: names are lower-cased and must be unique, failures are reported per-name in 'failed' without aborting the batch, and retries are safe via requestId. It stops short of auth/permission or quota context, so 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 the action and scope, and the four sentences each carry distinct information (constraints, partial-failure behavior, follow-on tools, retry key). The names clause is dense, packing normalization, uniqueness and failure reporting into one sentence, but nothing is wasted.

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

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

An output schema exists, so return values need no explanation, and the description still covers constraints, batch size, partial-failure semantics and idempotent retry. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is only 25% (requestId only), so the description must compensate; it does so for 'names' by specifying the 100-item cap, lower-casing normalization and project-scoped uniqueness. organizationId and projectId remain unexplained in both schema and description, so it is not fully compensating.

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 and scope ('Create up to 100 query clusters in a project') and even defines what a cluster is ('the groups tracked queries are organized in'). An agent can distinguish it from rename_cluster, delete_cluster and list_clusters without opening any schema.

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

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

Names the follow-on tools explicitly ('Assign tracked queries with add_tracked_queries_to_clusters, or let start_auto_clustering propose groups'), which effectively routes the agent. However, it gives no when-not guidance, e.g. checking list_clusters first or using rename_cluster when the group already exists.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds the consequential side effect that tracking begins immediately. It also explains the retry contract ('Pass a fresh requestId and reuse it if you retry'), which complements rather than contradicts 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 persistent-tracking effect is front-loaded in the first clause, followed by the discovery pointer and the idempotency note. Three tight sentences with little waste, though the phrasing is dense and slightly clause-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?

An output schema exists, so return values needn't be explained, and annotations carry the safety profile. The description covers the main behavioral surprise (immediate persistent tracking) and the retry semantics; it does not mention limits, billing or failure modes, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is only 17% (just requestId), so the description must compensate. It does add meaning for three params in prose ('website domains' and 'the names it is mentioned by', plus name), but organizationId and projectId are left entirely undescribed, so the gap is only partially filled.

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 gives a specific verb (Add) and resource (competitor to a project), then explains the persistent effect: its mentions and rankings are tracked alongside the brand's. This clearly separates it from update_competitor and delete_competitor, which only modify or remove an already-tracked competitor.

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 names an explicit discovery path ('list_untracked_competitors shows the brands AI answers name that are not tracked yet'), which tells the agent where to source candidates before calling this. It does not state exclusions (e.g. use update_competitor instead when the competitor already exists), so it falls just short of a full 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 only cover the safety profile (not read-only, not destructive, not idempotent); the description goes well beyond by disclosing the account-scoping constraint, permission/role requirements, the required human-confirmation sequence, and how the confirmationToken is obtained. This is exactly the context an agent cannot infer from structured fields.

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

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

Front-loaded with the action and ownership, then the scoping constraint, then the confirmation workflow, then permissions. Every sentence carries required information, though the confirmation-flow sentence is long and could be split for readability.

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

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

For a mutation tool with an output schema (so return values need not be described), the description covers the gating condition, auth requirements, and the mandatory preview/confirm workflow. An agent has everything needed to decide whether and how to call it.

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 33%, so the description must compensate, and it does so for the most critical parameter by explaining that confirmationToken comes from preview_operation and must follow explicit user agreement. The name parameter's constraints (maxLength) are left to the schema, and requestId is already documented there.

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') plus the ownership semantics ('owned by the caller'). This clearly separates it from update_organization, archive_organization, get_organization, and restore_organization in the sibling list.

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: only usable with a Mencoro connection not limited to one organization, requires organization:manage and the owner role, and mandates a preview_operation confirmation flow before invocation. It also names the sibling tool (preview_operation) and the exact argument to pass 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 declare readOnlyHint=false and idempotentHint=false; the description adds the practical safeguard that a fresh requestId reused on retry prevents a duplicate project, which is real operational context beyond the annotations. It does not contradict idempotentHint=false (server-side idempotency is not assumed; the client supplies the key) and adds retry semantics plus workflow ordering.

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 create statement, then workflow guidance. Every sentence is actionable, though the middle sentences on suggest_brand_names and list_untracked_competitors make it fairly dense for a single paragraph.

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 an output schema present, return values need no explanation, and the description covers the creation inputs, retry/idempotency behavior, and cross-tool sequencing. It stops short of stating permission or organization-scope requirements, but otherwise an agent has what it needs to call this 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 50%, and the description compensates by explaining what brandNames and websiteDomains represent in the monitoring context, plus the requestId retry rule ('reuse it only to retry this same call'). organizationId and name are left to the schema but are self-evident.

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

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

States a specific verb and resource (create a project that monitors a brand) and enumerates the core inputs: website domains, brand names, optional competitors. It also explicitly distinguishes itself from create_tracked_queries, which handles the follow-up step, so an agent can place it in the workflow without opening sibling schemas.

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

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

Gives explicit sequencing and alternatives: gather inputs from suggest_brand_names, propose everything to the user at once, add queries later with create_tracked_queries, and check list_untracked_competitors after the first run. It even notes no tool finds competitors, closing an obvious agent question.

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 (which only flag write/open-world/non-idempotent), it discloses that checks consume budget, that at most 100 combinations are created, that already-tracked/duplicate/unsupported-country Google AI Mode combinations are skipped and reported, and that a confirmationToken is mandatory. Annotations are not contradicted.

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 behavior, then the confirmation requirement, then the idempotency note — a logical order with little waste. It is dense but slightly long, and the skipping/cost details are packed into one clause.

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 costly, budget-spending mutation with an output schema present, the description covers the critical operational context: confirmation gating, idempotency, cost, and skip behavior. The gap is a few undocumented parameters (notably queryClusterIds), but no return-value explanation is needed given the 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 low (36%), and the description compensates well for the core parameters: it explains the combinatorial meaning of queryTexts/engines/countries, the 100-combination cap, and that each check spends budget. However queryClusterIds, locale, and organizationId remain undocumented, and checkFrequency semantics 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?

Opens with a specific verb+resource ('Start tracking queries') and precisely defines what gets created: the cartesian product queryTexts x engines x countries. It is clearly distinguishable from siblings like update_tracked_queries and delete_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?

Gives an explicit precondition workflow: call preview_operation first, show the returned plan/cost to the user, and only call this tool after explicit user agreement. It also states retry guidance for requestId, 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 declare destructiveHint=true and readOnlyHint=false, but the description goes further: it explicitly says the action is irreversible, discloses the non-obvious side effect (tracked queries are not deleted, they only leave the cluster), and explains the confirmationToken gating requirement. That is behavioral content the annotations 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 short sentences, front-loaded with the action and its scope, then the irreversibility warning, then the required workflow. No filler and the highest-risk information arrives early.

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?

An output schema exists, so return values need not be described. Combined with complete safety disclosure, the side-effect clarification, and the mandated preview/confirm workflow, an agent has everything required to call this destructive tool 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 0% across 5 parameters, so the description must compensate. It meaningfully explains the non-obvious confirmationToken parameter (how to obtain it and from which tool), but organizationId, projectId, clusterId, and requestId remain undocumented. It covers the one parameter that most needs explaining but not the rest.

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 ("Delete a query cluster") and immediately scopes the blast radius: tracked queries survive and merely leave the cluster. That distinction cleanly separates it from delete_tracked_queries and list_clusters in the sibling set.

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 prerequisite workflow: call preview_operation with tool "delete_cluster" and the same arguments, show the returned plan to the user, and only call this tool after explicit user agreement. This is exactly the when/when-not guidance an agent needs for a destructive operation.

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 flag destructiveHint/readOnlyHint/idempotentHint; the description goes further by naming the exact cascading data loss (mentions, search results, shopping results), declaring the operation irreversible, and describing the human-confirmation gating. That is material 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 tight sentences: effect and blast radius first, irreversibility second, required workflow third. No filler, and the most decision-critical 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?

An output schema exists, so return values need no explanation, and the safety/confirmation story is complete. The only gap is that the requestId parameter and the identifier parameters remain undocumented, which an agent may need to disambiguate.

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 must compensate. It explains confirmationToken in depth (how to obtain and when to send it), but organizationId, projectId, competitorId and requestId carry no meaning 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 precise verb (remove) and resource (competitor from a project) and enumerates the cascade scope: every mention, search result and shopping result. This clearly separates it from sibling deletions such as delete_cluster, delete_tracked_queries and archive_project.

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 precondition and workflow: a confirmationToken is required, obtain it by calling preview_operation with tool "delete_competitor" and the same arguments, show the plan to the user, and only call this tool after explicit user agreement. When-to-use and when-not-to-use are both spelled out.

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

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

Annotations already flag destructiveHint=true and non-idempotency, and the description adds substantial value on top: it names the collateral data destroyed (answers, matches, metrics), declares the operation irreversible, and documents the confirmationToken gate. This is exactly the extra behavioral context annotations cannot carry.

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

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

Three sentences, zero filler, front-loaded with the action and blast radius before the alternative and the mandatory workflow. Every clause earns its place.

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

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

For a destructive, gated mutation tool with an output schema (so return values need not be described), the definition covers purpose, scope, irreversibility, alternative path, and the token acquisition workflow. Nothing an agent needs in order to call this safely is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains the least obvious parameter (confirmationToken: how to obtain it via preview_operation and the user-agreement precondition) and confirms the 100-item cap that matches maxItems. It leaves organizationId, projectId and especially requestId unexplained, which is a real but smaller gap since those names are largely self-describing.

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 (Delete) and resource (tracked queries), plus the exact blast radius: 'together with their captured answers, matches and metrics history' and the batch limit of 100. An agent can distinguish this from pause_tracked_queries and delete_cluster 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 provides the when-not and the alternative: 'to stop spending budget without losing history, pause them with pause_tracked_queries instead.' It also spells out the required prerequisite workflow (preview_operation first, show plan, get explicit user agreement) so there is no inference required.

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 readOnlyHint=false, idempotentHint=false, openWorldHint=true, so the mutation and non-idempotency profile is partly covered. The description adds that this is an asynchronous background job requiring polling, which the annotations do not convey, and warns that the full list must be passed on update. It stops short of noting rate limits or what happens to concurrent jobs, but adds real value beyond annotations.

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

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

Front-loads the core action and the 'does not find new competitors' exclusion, then layers the workflow and parameter notes. It is dense but nearly every clause carries actionable information. Slightly long, yet no sentence is wasted.

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

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

A background mutation tool with an output schema, non-idempotent and open-world semantics is fully described: what it produces, how to retrieve it (get_job), how to apply it, and the scope flags. Nothing an agent needs to invoke 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 only 20%, so the description must compensate. It explains shoppingEnabled (looks at Google Shopping) and country (narrows to one market, ISO 3166-1 alpha-2), which the bare schema does not. organizationId and projectId are self-evident and requestId is documented in the schema; the two non-obvious flags are covered.

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: starts a background job that finds aliases/product/store names for the brand and existing competitors. It explicitly distinguishes itself from siblings by ruling out new-competitor discovery ('It does not find new competitors') and by naming suggest_brand_names-adjacent scope. An agent can tell exactly what this produces.

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 the user, then add chosen names with update_project (brand) or update_competitor (by competitorId), passing the full list including existing names. It also states when each option applies (shoppingEnabled, country). This is unusually complete 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 declare it is a non-read-only, open-world operation, but the description adds crucial behavioral context the annotations cannot: it runs asynchronously as a background job that must be polled via get_job, requires an active subscription, and its results are meant for user review before tracking. The write/approval workflow is well disclosed.

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

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

Three dense sentences, each earning its place: the action, the excludeQueries nuance, the follow-up workflow, and the subscription prerequisite. The core verb 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?

With an output schema present, the description needn't explain returns, and it covers the async workflow and subscription gate well. The main residual gap is the undocumented country/language/org/project parameters, but the agent has enough 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 coverage is only 14% (just requestId), so the description must carry more burden. It does clarify the 'input' seed semantics and that excludeQueries leaves out already-tracked queries, but country, language, organizationId, and projectId receive no explanation anywhere. 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?

The description gives a specific verb and resource ('Start a background job that proposes search keywords for a project') and clarifies the input seed types (topic, product, URL). It is clearly distinguishable from siblings like discover_brands and discover_prompts 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 lays out the full workflow: poll get_job for the result, review with the user, then track via create_tracked_queries, plus the prerequisite 'Requires an active subscription.' It does not explicitly contrast when to prefer this over discover_brands/discover_prompts, so it stops short of full 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=false, destructiveHint=false, and openWorldHint=true, so the write/open-world profile is covered. The description adds that the work is asynchronous (background job) and requires an active subscription, which are genuinely useful behavioral facts. It stops short of detailing job timing or failure behavior, so a 4 is appropriate.

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

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

Front-loads the purpose, then the workflow and the subscription requirement in economical sentences. Slightly dense in the middle sentence but every clause carries actionable meaning.

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?

An output schema exists, so return values need not be explained, and the async workflow is covered. However, for a seven-parameter tool with very low schema coverage, the description omits meaning for most inputs, 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 only 14%, so the description must compensate, yet it only explains excludeQueries. The other six parameters (input, country, language, projectId, organizationId, requestId) get no semantic explanation in either field, leaving most of the interface 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 and resource: 'Start a background job that proposes the questions people ask AI assistants about a topic in one country.' It clearly distinguishes itself from the sibling discover_brands and discover_keywords by naming the artifact it produces (prompts/questions).

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 workflow and alternative routing: poll get_job for results, review with the user, then use create_tracked_queries, and it explains that excludeQueries drops already-tracked ones. It also states the prerequisite (active subscription). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavioral context beyond that: the exact return shapes ({code,label} vs {id,name}) and the hard rule to pass code/id and never label/name.

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 purpose, then the return shapes, then the critical code-vs-label rule. Dense but every sentence carries information; the example literals add slight length without much new meaning.

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?

An output schema exists, so the description didn't need to describe return values, yet it helpfully pins down the exact fields and the code/id convention. The remaining gap is input parameter meaning, which no other field covers.

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

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

Schema description coverage is 0% for two required parameters, and the description never explains what organizationId or projectId are, their format, or where to obtain them. It compensates only on the output side, leaving the inputs undocumented in both schema and 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 (discover) and a precise resource set (engines, countries, keyword clusters, competitors configured on a project), which cleanly separates it from siblings like list_clusters or list_untracked_competitors that each cover only a subset.

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 before filtering" plus the statement that subsequent metric tools need these values gives clear usage context. It doesn't name a specific alternative tool or a when-not-to-use case, so it falls 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, and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond the schema: the list is UNFILTERED by ownership (includes competitors and third parties) and only AI engines carry citations. It also describes the returned per-source metrics, which is extra context.

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 groupBy distinction and ownership caveat come early, followed by return metrics and constraints. Slightly long, but nearly every clause carries information an agent needs; no filler 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 an output schema present, return values needn't be explained, yet the description still outlines the per-source metrics, and it adds the retention-window and AI-engine constraints. Combined with the annotations, an agent has enough to call it correctly; minor gaps remain around pagination (limit/offset).

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

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

Schema description coverage is only 25%, so the description must compensate. It does explain the enum that matters most — groupBy=domain vs page (host vs exact URL) — and constrains engines to AI-only engines. It leaves limit/offset/defaults unaddressed, but those are intuitive and low-risk.

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 (get/list) and resource (cited domains/pages) with scope (most cited across a project's AI answers in a date window). The distinction between groupBy=domain and groupBy=page is front-loaded, so an agent can tell this apart from sibling analytics tools immediately.

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 date window must fall within the retention window, only AI answer engines produce citations, and it answers 'which sites/pages does the AI cite for me vs competitors'. However, it names no alternative sibling (e.g. list_ai_responses or get_mention_mix) and offers no explicit when-not-to-use guidance.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuine beyond-schema context: a data-retention constraint on dates and the shape of the result (per-cluster rows). It does not cover pagination or default engine/country scope, which keeps it from 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?

The core payload, grain and date constraint are front-loaded in the first two sentences, with the example questions last. It is efficient and free of filler, though the third sentence is arguably optional given how self-explanatory the tool name is.

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?

An output schema exists, so the description need not explain return values, and annotations carry the safety profile. The description still supplies the key operational constraint (retention window) and the per-cluster grain. Missing details are minor – e.g. what happens when a cluster has no data, or defaults for engines/countries.

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

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

Schema description coverage is 50%, with engines, countries, queryClusterIds and includeUngroupedQueries documented in the schema itself. The description only adds meaning to the date pair via the retention-window rule; organizationId, projectId and the filter arrays get no elaboration. Baseline 3 is appropriate given the partial compensation.

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 ('rank-tracking metrics broken down per keyword cluster') and even states the output grain – one row per cluster with positions, share of voice and sentiment. That clearly separates it from get_sentiment_breakdown, get_share_of_voice_formula and get_rank_tracking_time_series. It stops short of naming a sibling alternative explicitly, so it is clear but not fully differentiating.

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 through example questions ('which keyword clusters are strongest or weakest', 'how does my niche compare to my generic queries'), which helps an agent recognize the right scenario. However, there is no explicit when-not guidance and no named alternative for the adjacent time-series or single-query tools, so routing remains partly inferential.

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's job is added context—which it delivers by spelling out the returned row contents (co-appearance counts, win/loss/tie by best position, win rate, average positions, a representative query) and the retention-window and tracked-competitor constraints. It doesn't discuss pagination or result sizing, keeping it from 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?

Core comparison is front-loaded in the first sentence and the output shape follows immediately. Slightly dense and the trailing example-question list is somewhat redundant with the lead sentence, but nothing is wasted to the point of harm.

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 an output schema present, the description needn't restate return structure, yet it usefully previews the per-competitor row fields. Constraints (tracked-only, retention window) and the optional focus param are covered, leaving only minor gaps around engine/country filtering semantics.

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 43%, so the description must compensate, and it does explain competitorId (optional single-rival focus, UUID sourced from get_available_filters) and the date retention constraint. However it adds little for engines and countries beyond what the schema already documents, leaving part of the low-coverage surface unexplained.

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

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

States a specific verb (compares who is named higher) and resource (co-occurring AI answers between brand and competitor), and distinguishes itself from sibling analytics tools by defining the exact head-to-head comparison. An agent can tell this apart from get_share_of_voice_formula or get_mention_mix 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 clear operational context: 'Tracked competitors only', dates must be inside the retention window, and competitorId optionally narrows to one rival. It also lists triggering questions ('who wins when we both appear'). It stops short of naming an explicit alternative or exclusion condition, so it isn't a full 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, but the description adds substantial context beyond them: polling cadence, that discover_prompts typically finishes in 15 minutes and times out around 30, and the failure taxonomy (timed_out, provider_failed, submission_failed, internal_error) with error.message guidance.

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 progressive operational detail. Dense but each sentence contributes (poll behavior, timing, error codes). Slightly long, but no filler 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?

For a polling tool with an output schema and full safety annotations, the description covers behavior, timing, and error handling well. The only gap is identifying the two required inputs, which the schema does not document either.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining jobId and organizationId, yet neither parameter is described. It implies jobId originates from the job-starting tools but never states the identifier source explicitly, and organizationId is entirely unexplained.

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

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

The first sentence states a specific verb and resource: the status and result of a background job. It also names the exact sibling tools that create such jobs (discover_brands, suggest_brand_names, discover_keywords, discover_prompts, start_auto_clustering), so an agent can immediately place it relative to the job-starting 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?

Explicit operational guidance: poll every few seconds until status is completed or failed, and do not restart the job while it is pending or running. It also gives an expected timeline and failure conditions, which is exactly the kind of when-to-use context an agent needs to avoid duplicate work.

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 genuinely useful context beyond that: the content is public documentation, no account data is touched, and no sign-in is required — which explains why it can be called before authentication.

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 opening clause is well front-loaded, but the following sentence is a sprawling enumeration of ~16 content areas that largely restates the parameter enum, adding bulk without new decision-relevant information. It would be tighter as a short scope statement plus reliance on the enum for the topic list.

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

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

An output schema exists, so return values need no explanation, and the description covers purpose, invocation pattern, scope and authentication posture. For a single-optional-enum read tool this is nearly complete; only the redundancy in the topic enumeration keeps it from being fully efficient.

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 covers the single parameter at 100% and carries the full enum, and the description reinforces it by stating that omitting the topic (or passing 'index') yields the topic list. That clarifies the null/default behavior beyond the bare schema, though it does not add format or resolution guidance.

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 ('Answer questions about Mencoro itself from its public guide') and enumerates the domains covered, so an agent can tell this documentation/guide tool apart from data tools like get_metric_glossary or get_share_of_voice_formula. It also pins down scope with 'No account data; works without signing in.'

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 two-step procedure ('Call it without a topic for the index, then with the topic that answers the question') and an explicit boundary condition ('No account data'), which steers the agent to account-scoped siblings when guide content is not what is wanted. Nothing about when to invoke it 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?

Goes well beyond the annotations by disclosing that counts are raw per-pass rows, exclude cited links, and therefore differ from share-of-voice inputs (which average each check over passes and weight links). That is exactly the kind of non-obvious behavioral caveat 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?

Front-loads scope and the critical raw-count caveat, then routes to alternatives, then examples. A bit dense but every sentence carries routing or caveat value; slightly long for a 5.

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?

An output schema exists so return values need not be explained. The description still supplies the calculation caveat, scope exclusions, the retention constraint, sibling routing, and example questions – complete for a read-only aggregation 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 33%, so the description must compensate. It adds the date retention-window constraint (applies to dateFrom/dateTo) and clarifies that grouping is fixed to type/tone/qualifier. It does not add semantics for engines or countries beyond what the schema already documents, so not 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?

Specific verb+resource+grouping: the project brand's own AI text-mention counts over a date window grouped by type, tone, and qualifier, with explicit scope (own brand only; competitors and unrelated brands excluded). It distinguishes itself from get_sentiment_breakdown and get_mention_samples by naming both 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?

Explicit routing: use this for mention composition, use get_sentiment_breakdown for the positive/neutral/negative split, use get_mention_samples for actual texts. Also gives a retention-window constraint and example questions. Nothing left to inference.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the safety profile is covered. The description still adds real value beyond them: the data retention window constraint on dates and the limit range (1-50, default 20), which 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?

Front-loaded with what the tool returns, then alternatives, then filters. Dense but mostly earns its place; the trailing 'Answers questions like...' sentence is mildly redundant with the opening statement.

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?

Output schema exists so return values need no explanation, and the retention-window and pagination constraints are disclosed. Only gap is the absence of guidance on sortBy and offset semantics for a 12-parameter tool, which is minor given the structured coverage.

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% across 12 parameters, so the description must compensate. It does name the filterable dimensions (engine, sentiment, mention type, competitor) and the limit bounds, but it omits any meaning for sortBy, offset, and countries (which is in fact a filter too). Partial compensation, not full.

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

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

States a specific verb and resource: a paginated sample of raw AI mention texts for qualitative review and sentiment-label verification. It explicitly names and distinguishes itself from siblings get_sentiment_breakdown and get_mention_mix.

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?

Give explicit routing: 'Use to READ individual mentions', then names the aggregate alternative (get_sentiment_breakdown) and the count-by-type/tone alternative (get_mention_mix). The when-to-use decision is fully resolved without opening sibling schemas.

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 and closed-world, so safety is settled. The description adds genuinely new context: it is a 'static reference; no project data,' telling the agent the result is independent of project state and safe to call speculatively — a meaningful behavioral disclosure.

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

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

Three tight sentences: what it does, what it returns, when to call it. The routing instruction is front-loaded and nothing is 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?

An output schema exists, yet the description still sketches the return shape (synonyms, unit, range, direction, serving tool, examples) and states the static nature. Nothing an agent needs to decide to call it is missing.

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

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

Schema description coverage is 0% and the single required parameter, organizationId, is never explained in the description. With only one parameter and a rich output schema, the omission is minor but real; baseline 3 is appropriate.

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

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

The description states a specific verb (Map) and resource (plain-language request → Mencoro metric and tool), plus it enumerates the fields returned. This clearly separates it from data-querying siblings such as get_organization_overview or get_cited_sources, which return project data rather than a static mapping.

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 trigger list: call first when a request is vague, non-technical, in another language, or doesn't match a tool name — which implicitly defines the when-not case. It stops short of naming a sibling as the alternative (e.g. get_mencoro_guide or get_available_filters), so it is strong but not fully explicit about alternatives.

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 the returned fields' composition, but since an output schema exists, that is largely redundant and it discloses no auth requirements, failures, or scoping 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?

Two tight sentences, front-loaded with the content summary and ending with the actionable prerequisite hint. No filler, though the first clause is a fragment rather than a stated verb.

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 a full output schema and read-only annotations, the description only needs to frame the purpose and the ID prerequisite, both of which it does. The missing piece is differentiation from get_organization_overview, a plausible sibling collision.

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% for the single organizationId parameter. The description partially compensates by telling the caller where to obtain the ID (via list_projects), which is useful, but it never describes the ID's format or source semantics beyond that hint.

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 (organization) and enumerates exactly what is returned: profile, status, caller's role, and active member/project/pending-invitation counts. This is a clear read purpose, though it never states a verb and does not distinguish itself from the sibling get_organization_overview.

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 one concrete prerequisite workflow — 'Use list_projects first to find the organizationId' — which is genuinely actionable. It does not, however, say when to prefer this over the sibling get_organization_overview or list_members/list_projects, so routing guidance is only partial.

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 structurally. The description adds one genuinely non-obvious behavioral fact — that it takes NO date window and is a current-state snapshot — which annotations cannot express. It says nothing about auth requirements, aggregation lag, or large-organization performance.

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 resource and output shape, then the usage constraint and the example question. The middle sentence is dense with column names but each earns its place; the only redundancy is restating the snapshot/no-date-window point in the example sentence.

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?

Aggregate tool with an output schema present, so return values need no further explanation — yet the description still names the row grain and aggregate. Required param, routing alternative, and the no-date-window constraint are all covered; 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 description coverage is 0% and the single organizationId parameter is undocumented, so the description must compensate. It scopes the tool to an organization and clarifies the absence of date parameters, but adds no meaning about what organizationId accepts or where to obtain it. Marginal compensation for a one-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 ('rank-health board across all active projects in an organization') and enumerates the returned columns — share of voice, mention rate, position, positivity, query counts — so the agent knows exactly what this tool produces. It also explicitly distinguishes itself from the per-project time-series 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?

Gives both when-to-use ('company-wide summary of share of voice and sentiment across all my projects') and when-not ('for date-ranged comparison, call the per-project tools ... for each project id returned here'), naming the specific alternative. Routing is unambiguous.

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 by structured data. The description adds meaningful context about the shape of the returned entity, but says nothing about failure modes (e.g., project not found, org access) or data freshness.

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 sentence with no filler, and the most important content (what you get back) is front-loaded. It is slightly list-heavy 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?

With an output schema present, the description's return-value enumeration is arguably redundant, and the key remaining gap – the two undocumented required inputs – is left unaddressed. For a simple two-parameter read tool the annotations plus output schema carry most of the load, so this is adequate but not complete.

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

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

Schema description coverage is 0% and there are two required parameters (organizationId, projectId), yet the description never mentions them or clarifies their relationship. The only 'id' discussion concerns competitor ids in the output, not the inputs, so the description does not 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?

The description names the resource and enumerates exactly what is returned: name, status, monitored domains, brand names, and competitors with their ids. That is far more specific than a bare 'get a project', though it never explicitly states the retrieval is keyed by organizationId/projectId or contrasts itself with list_projects/get_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?

The only usage signal is incidental: 'competitors with their ids (update_competitor and delete_competitor take them)', which usefully chains this read to downstream mutations. There is no guidance on when to call get_project versus list_projects or get_organization, and no prerequisites 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context the annotations don't: the data-retention window constraint on dates and the fact that results are aggregated summaries spanning competitors, sentiment, and position buckets.

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 scope phrase and metric list, then the routing guidance, then the retention caveat and example questions. The metric enumeration is long but each item is informative; no filler 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 an output schema present, return values need not be described, yet the description still conveys the shape of the answer. Combined with sibling routing, the retention prerequisite, and usage triggers, an agent has everything needed to call this 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 coverage is 50%: the optional filters (engines, countries, queryClusterIds, includeUngroupedQueries) are documented in the schema, while the four required identifiers/dates are not. The description only partially compensates by tying the date parameters to the retention window and gesturing at a 'date window' scope; it says nothing about how organizationId, projectId, or the filters shape the aggregation.

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 (project rank-tracking summary), the scope (aggregated over a date window), and enumerates the metrics returned. It explicitly separates itself from siblings by calling out 'per-cluster or time-series tools', so an agent can route correctly without opening another 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?

States a preference ordering ('prefer it before the per-cluster or time-series tools'), gives concrete interrogation triggers ('how visible is my brand', 'am I ahead of competitors'), and adds a hard prerequisite that dates must fall within the retention window.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior: the delta is computed against the immediately preceding equal-length window, dates must fall within the data retention window, and each row carries current position/share/sentiment plus a signed delta. It does not mention pagination behavior or result size caps, which is the only notable gap.

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

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

Front-loads the ranking definition before the row shape and sort mechanics, and each sentence adds information (comparison window, row granularity, sort semantics, retention constraint, example questions). It runs long and slightly restates the gainers/losers idea, but there is no filler sentence.

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 read tool with an output schema and full annotation coverage, the description supplies the comparison mechanics, sort semantics, retention constraint, and question routing — enough to call it correctly. The residual gap is undocumented pagination identifiers (limit/offset), which the schema defaults partly cover.

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% (10 params), so the description carries more burden than usual. It does explain the two tricky params well — sortBy picks which trend delta to rank by, and sortOrder desc = gainers / asc = losers — and clarifies that dates are bounded by retention. But limit, offset, organizationId, projectId, and the date params receive no semantics anywhere, leaving a real 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 — ranks a project's tracked queries by metric change between adjacent equal-length windows — and defines the row granularity (one engine + country per tracked query). An agent can distinguish this from the sibling time-series tools (get_tracked_query_time_series, get_rank_tracking_time_series) because it is a cross-window comparison, not a series. The sign convention (positive = improved) removes ambiguity about what a 'mover' is.

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 triggering context with example questions ('which queries moved the most', 'my biggest gains and drops versus last period'), which tells the agent when this tool fits. It does not, however, explicitly name an alternative or state when not to use it versus the time-series or search_tracked_queries siblings. Clear usage context without exclusions.

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 the read-only, idempotent, non-destructive profile, so the bar is lower. The description still adds real behavioral context: the data-retention window constraint on dates, the response-size tradeoff across granularities, and the fact that competitor series are optional additions. It does not cover auth needs or rate limits, but with safety annotations present this is solid.

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

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

The core purpose and the granularity/compactness guidance are front-loaded, and the sentences are dense and free of filler. The trailing 'Answers questions like ...' sentence is useful routing context but slightly softens an otherwise tight definition.

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 an output schema present, the description covers the essential calling axes (date window, retention constraint, bucketing, optional competitor series, per-engine split). It is complete enough to invoke correctly, though it omits any disambiguation against sibling time-series and stats tools.

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

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

Schema coverage is 50% and there are 10 parameters. The description echoes granularity options and mentions competitor lines and per-engine splitting, but leaves the meaning of flags like includeUngroupedQueries and the organization/project/date identifiers to the schema. It adds marginal value over the structured fields rather than compensating for the half of parameters that lack 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?

States a specific verb+resource+scope: a time series of rank-tracking metrics for a project over a date window, with the bucketing axis named. It is clear what the tool returns, but it never distinguishes itself from the closely related get_tracked_query_time_series or get_project_rank_tracking_stats, so an agent must infer which time-series tool 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?

Gives genuine usage context by naming the questions it answers ("what changed in my AI visibility", "share-of-voice trend split by engine") and advises weekly/monthly for long windows. However it names no alternative tool and gives no when-not condition, so the agent gets implied rather than explicit routing guidance for a family with several similar reads.

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 a closed world, so safety is covered. The description adds genuinely useful context beyond that: the breakdown dimensions returned and the data-retention constraint on dates, which affects call validity.

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, then routing, then the retention caveat; the illustrative questions ('is anything negative being said about my brand') are slightly redundant but aid intent matching. No sentence is wasted, though the description is a touch longer than strictly needed.

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 an output schema present, return values need not be explained, and the description covers purpose, alternatives, and the retention constraint. It leaves the filtering semantics (countries, query clusters) to the schema, which is acceptable but not complete for an 8-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 only 50% across 8 params; the description adds little parameter-level meaning beyond reiterating the date window (already in schema) and gesturing at engines via 'per AI engine'. Countries, queryClusterIds, and includeUngroupedQueries semantics live only in the schema, so the description does not 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 ('positive/neutral/negative sentiment split of the brand's AI mentions over a date window') plus the grouping dimensions (per AI engine, per competitor). It clearly distinguishes itself from get_mention_mix and get_mention_samples, so an agent can route without opening schemas.

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

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

Gives explicit when-to-use guidance ('Use for tone/sentiment questions') and names two alternatives with the exact condition that selects each ('brand's own mention counts by type... use get_mention_mix', 'read the actual mention texts... use get_mention_samples'). It also flags the retention-window prerequisite for the date parameters.

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 safety is covered. The description adds a genuine behavioral trait - the formula is global rather than project-specific - though the follow-on "scoped to a project you can access" is slightly muddled and not explained further.

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

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

Three short sentences, front-loaded with the payload content before the usage hint. No filler, though the final scope sentence is the least clear and could be 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?

An output schema exists, so return values needn't be described, and the safety profile is covered by annotations. What's missing is clarity on the parameter roles and on the apparent tension between a 'global' formula and required project scoping - an agent could still invoke it, but the scoping story is incomplete.

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 two required parameters (organizationId, projectId), so the description carries the full burden. It mentions project scoping but never explains what either parameter identifies or how organization vs project scoping interacts with the stated global nature, leaving the ambiguity unresolved.

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 and its content: the constants behind the share-of-voice score (per-mention-type base weights and tone/qualifier multipliers). An agent can tell this is a read of formula constants rather than a computed metric. It doesn't explicitly name the sibling it differs from (e.g. get_metric_glossary), so it falls 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?

"Use this to explain how the share-of-voice metric is derived" gives one clear use case, and the scope note adds context. But it names no alternatives and no conditions for choosing it over get_metric_glossary or the actual share-of-voice metric tool, so guidance is implied rather than explicit.

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

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 fully covered upstream. The description's list of returned settings partly duplicates the output schema rather than adding behavioral context (no note on auth scope, missing-record behavior, or freshness of last-checked data).

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

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

Two tight sentences with zero waste: the payload contents come first, the id-discovery pointer second. Nothing redundant or 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?

An output schema exists, so return values need no explanation and the annotations carry the safety story. The remaining gap is that a three-required-parameter lookup with 0% schema coverage leaves the meaning and scoping of organizationId/projectId 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 description coverage is 0% and none of the three required parameters (organizationId, projectId, trackedQueryId) is explained anywhere. The description only indirectly hints that trackedQueryId comes from search_tracked_queries; it does not clarify scoping by organization/project, 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 (get) and resource (tracked query) and enumerates what the record contains: text, engine, country, status, check frequency, passes, clusters, last-checked. It also names the sibling search_tracked_queries, so an agent can distinguish it from get_tracked_query_matches and get_tracked_query_time_series by the fact that this is a single-record settings fetch.

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 pointer 'Find ids with search_tracked_queries' tells the agent where the required id comes from, which is genuine usage context. However, it gives no guidance on when to prefer this over the closely named get_tracked_query_matches or get_tracked_query_time_series siblings, so the routing is only partially 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 the safe read profile (readOnlyHint, idempotentHint, openWorldHint=false, destructiveHint=false), so the bar is lower, and the description adds genuinely useful behavior: default newest-first ordering, the YYYY-MM-DD date format, and that dates default to the whole retention window. It stops short of explaining pagination or result-size 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 a one-line summary, then the two kind modes, then defaults for ordering and dates. Sentences are dense and earn their place, 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?

An output schema exists, so the description needn't enumerate return values, and it still sketches them usefully (position, sentiment, context). For a 9-parameter tool with 0% schema coverage, it could say more about limit/offset paging, but the required call path (org/project/query/kind plus dates) is covered.

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 carry the load and it only partially does: it adds real meaning for kind (mention vs serp) and for the date/sort parameters (format, defaults, ordering). limit, offset, organizationId, projectId and trackedQueryId remain undocumented here and in the schema, leaving the pagination controls opaque.

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 resource (the individual results/results rows behind a tracked query's metrics) and disambiguates its central enum by explaining what kind "mention" and kind "serp" each return. It is clear what the tool produces, though it never names or contrasts a sibling (e.g. get_mention_samples, 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?

Usage is implied rather than stated: an agent can infer you call it when you want the rows behind the aggregate metrics, and the kind semantics guide which mode to pick. But there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance, so selection against siblings is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the burden is lower. The description still adds real behavior: the tracked query fixes engine and country so they aren't parameters, optional per-competitor lines, granularity bucketing, and the retention-window limit.

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

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

The core purpose and scoping constraint are front-loaded, and every following sentence carries distinct information (ID lookup, competitor lines, granularity heuristic, retention limit). 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 an output schema present, return-value explanation isn't required, and the description covers identity, granularity, competitor lines, and date constraints. A brief note on the required org/project scoping or date format would make it fully 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 low (29%) and the description partly compensates: it explains granularity semantics, competitorIds as extra series, and clarifies that engine/country are not parameters. However it leaves organizationId, projectId, and the date format for dateFrom/dateTo 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?

The description names a specific verb+resource (time series of rank-tracking metrics for ONE tracked query) and immediately scopes it (bucketed by granularity, one query). It distinguishes itself from the sibling get_rank_tracking_time_series by emphasizing the single-query scope, letting an agent pick correctly.

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 routing guidance ('Use search_tracked_queries to find a trackedQueryId'), a heuristic ('Prefer weekly or monthly for long windows'), and a constraint ('Dates must fall within the data retention window'). It doesn't explicitly contrast with the broader get_rank_tracking_time_series sibling, so not a full 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 read-only/idempotent/no-destructive, so the description's job is to add scope semantics — and it does: never-checked and overdue counts are scoped to active queries only, overdue means past the check-frequency interval, and it explicitly states this is a current-state snapshot with no date window. That last point is genuinely useful for avoiding a wrong call with a date parameter. It omits any note on cost/latency or how large the 'sample' of overdue queries is.

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

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

Front-loaded with what the tool returns, followed by scope caveats and then use-case questions. The final sentence of example questions largely restates the opening enumeration ('overdue, paused, or never checked' duplicates the count list), which is mild redundancy but not enough to hurt 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?

An output schema exists, so return structure needn't be spelled out — yet the description still usefully previews the contents and the scoping rule for overdue/never-checked. Combined with the explicit 'no date window' note and the snapshot framing, an agent has enough to call it correctly; only ID semantics remain unaddressed.

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 organizationId and projectId, but the names are self-explanatory and the description establishes the project-scoped subject ('a project's tracked queries'). It does not state requiredness, ID format, or whether organizationId must match the project's owning org, leaving the schema to carry undocumented parameters.

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?

Starts with a specific resource and output: 'Coverage summary for a project's tracked queries', then enumerates the exact counts returned (total, active, paused, never-checked, overdue). This is clearly distinguishable from siblings such as get_project_rank_tracking_stats or get_tracked_query, which cover different aspects of tracking.

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 usage framing — 'Answers what is stale / not being tracked in one call' — and lists concrete triggering questions (which queries are overdue, paused, never checked; how fresh is my data). It does not, however, name an alternative sibling tool or state when not to use it, 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: entitlements are populated only for owners and are null for other members, matching the web app. That is real context beyond the annotations.

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

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

Two sentences, front-loaded with what is returned and then the action guidance; every clause earns its place by conveying scope, ownership visibility, or usage timing. Slightly dense but not padded.

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 an output schema present, the description needn't explain return values, yet it usefully flags the owner-only entitlements nuance. For a one-parameter read tool with strong annotations, little is missing beyond the org identifier format.

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

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

Schema description coverage is 0% for the single organizationId parameter, and the description only implies org scoping via possessive phrasing ('An organization's subscription'). It never states the expected identifier format, so it does not compensate for the schema gap, but a single obvious param keeps this near 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 states a specific resource set — subscription, tracked-query count, projected monthly checks, and plan entitlements — which is more concrete than the name alone. It distinguishes itself implicitly from list/get siblings like get_organization_overview, but never names a sibling to sharpen the boundary.

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 a clear prescriptive context: 'Use it before creating tracked queries or raising check frequency, to stay within the plan.' That tells the agent when this tool is relevant, though it names no alternative tool or explicit when-not condition.

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=false, destructiveHint=false, and openWorldHint=true, but the description adds substantial context: the confirmationToken gate, the required organization:manage permission plus owner role, and the no-op behavior for existing members. It does not describe response content, though an output schema exists to cover that.

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 side effect, then the precondition workflow, then permissions. Nothing is wasted, though the confirmation-token sentence is long and could be split for faster scanning.

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 tool with a required confirmation token, permission requirements, and an existing output schema, the description covers preconditions, side effects, idempotency-adjacent edge cases, and authorization. An agent has everything needed to call 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 coverage is only 20% and the description compensates well for the key parameters: email semantics, the three role values, and the purpose of confirmationToken. organizationId and requestId are left to the schema (requestId is documented there), so it stops short of full coverage but adds real meaning.

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 three allowed roles, and describes the resulting side effect (acceptance email). It is clearly distinguishable from siblings like list_members, update_member, and cancel_invitation.

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 workflow: call preview_operation with tool "invite_member" and these arguments first, show the plan, and invoke only after explicit user agreement. It also states what happens on an already-member address (nothing, reported back), covering both when-to-use and an edge case.

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 behavior beyond the annotations: default sort is newest-first, results are filterable by engine/query/date, and the date format is YYYY-MM-DD. It still omits pagination behavior (default limit 20, max 100, offset), which matters for a list tool.

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, then filters, then the default order, then the routing cue. No sentence is filler and nothing is repeated from the name or title.

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

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

An output schema exists, so return values need not be explained, and the description covers the record contents plus the main filters well. The remaining gap is pagination guidance on limit/offset for a bounded list (default 20, max 100), which an agent calling repeatedly 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 description coverage is 0% across 9 parameters, so the description carries real burden. It explains engines, trackedQueryId, dateFrom/dateTo (with the YYYY-MM-DD format), and the sortOrder default, but says nothing about limit, offset, organizationId, or projectId, leaving a meaningful portion undocumented anywhere.

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 resource (captured AI answers for a project's tracked queries) and enumerates what each record contains: answer text, engine, capture time, cited sources. It explicitly distinguishes itself from sibling metric tools, 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?

Gives a clear use case ('read what an engine actually said') and an exclusion ('for aggregates use the metric tools'), which is strong routing guidance. It does not name the specific metric sibling (e.g. get_mention_mix) but the boundary is unambiguous enough to act on.

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 that results are returned by name with ids, but says nothing about pagination, sorting behavior, or whether clusters are returned unpaginated in practice.

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 phrase, front-loaded with the resource and clarified by a parenthetical. It is efficient, though the fragment form makes it slightly terse for a tool with five parameters.

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?

An output schema exists so return-value detail is unnecessary, and annotations cover safety. However, for a list tool with limit, offset and sortOrder, the absence of any pagination or ordering guidance leaves a real 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 five parameters, so the description must carry the burden and largely does not. It implies project scoping ('A project's') but is silent on organizationId, limit/offset pagination, and the sortOrder enum.

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

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

The description names a specific resource (a project's query clusters) and defines what a cluster is, plus what is returned (names and ids). It is clear enough to separate from create_clusters, delete_cluster, rename_cluster and get_cluster_breakdown, though it does so by resource naming alone rather than explicit contrast.

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

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

There is no guidance on when to call this versus alternatives such as get_cluster_breakdown, get_tracked_query or search_tracked_queries. The description implies a browse/list use case but never states it or names any sibling.

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