Mencoro

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

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false); the description goes further by disclosing the actual side effects (creates clusters, moves tracked queries), name normalization, existing-cluster reuse instead of duplication, and idempotency behavior via requestId. This is meaningful behavioral context an agent cannot derive from the annotations alone.

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

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

Four sentences, each carrying distinct information (action, naming/reuse rule, preview prerequisite, idempotency key). The main action is front-loaded and there is no filler or repetition of the 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?

For a multi-step, stateful mutation the description covers the prerequisite (view proposal), the side effects, the naming/reuse semantics, and the retry/idempotency contract. An output schema exists, so return values need not be explained. Nothing needed 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 25%, so the description must compensate. It fully explains the non-obvious requestId (fresh key, reuse only on retry) and ties jobId to the start_auto_clustering job, but organizationId and projectId are left to inference. Strong on the parameter that matters, silent on the trivial ones.

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 ('Apply the grouping a completed start_auto_clustering job proposed') and explicitly names the producer sibling (start_auto_clustering), the naming convention shared with create_clusters, and the preview tool (get_job). An agent can distinguish this from create_clusters, start_auto_clustering, and set_tracked_query_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?

Gives explicit workflow guidance: show the proposal via get_job first, and only apply after. It also names the retry condition ('reuse it if you retry'), routing the agent correctly between generating a proposal, previewing it, and applying 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 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?

Goes well beyond the annotations: discloses that names are lower-cased, must be unique in the project, and that individual failures are reported in 'failed' without aborting the batch (partial-failure semantics). It also explains the requestId idempotency contract, which is valuable given idempotentHint=false.

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

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

Front-loaded with the core action and scope, then constraints and workflow. Dense but every sentence carries useful information; the count cap and uniqueness rule are integrated rather than 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?

An output schema exists, so return-value explanation is unnecessary. The description covers the operation's key constraints and failure behavior, though it leaves the organizationId/projectId scoping and any permission requirements 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 only 25%, so the description must compensate. It adds real meaning for 'names' (lower-casing, uniqueness, batch cap) and 'requestId' (fresh key, reuse on retry), but says nothing about organizationId or projectId scoping beyond naming the project.

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

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

States a specific verb+resource ('Create up to 100 query clusters') and defines what a cluster is ('the groups tracked queries are organized in'). It names sibling tools (set_tracked_query_clusters, start_auto_clustering) so the agent can place it within the workflow.

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?

Identifies the related follow-up actions (assigning queries via set_tracked_query_clusters, or letting start_auto_clustering propose groups), which clarifies the workflow context. It does not explicitly state when NOT to create clusters versus using auto-clustering, so the exclusion is only implied.

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

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

Annotations only declare it is a non-read-only, non-destructive, non-idempotent write. The description adds genuinely new behavior: once added, the competitor's mentions and rankings are tracked alongside the brand's, which tells the agent about durable side effects. Retry semantics via requestId are also disclosed, though permission/auth requirements are not.

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

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

Three compact sentences, front-loaded with the core action and effect, then the discovery hint, then the retry rule. No filler and nothing redundant with the schema.

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

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

With an output schema present, return values need not be described, and the description covers the action, its tracking consequence, the alternative source of candidates, and retry behavior. The main remaining gap is the unmentioned organizationId and array-shape expectations.

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

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

Schema coverage is only 17% (only requestId is documented inline), so the description has to compensate and partially does: it names the name, websiteDomains and brandNames payloads and ties the record to a project. organizationId is never explained and no format or cardinality guidance is given for the arrays.

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

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

States a specific verb and resource ('Add a competitor to a project') plus the three payload concepts it carries (website domains, brand names), and the verb cleanly separates it from update_competitor and delete_competitor. It also names discover_brands as the upstream proposal source, so the agent can place it in the workflow.

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

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

Points at discover_brands as the tool that proposes competitors, giving real when-to-use context, and explains the retry condition for requestId. It stops short of an explicit exclusion (e.g. 'use update_competitor instead to change an existing one'), so it is clear context without full routing rules.

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 idempotentHint=false, so the safety profile is partly covered. The description goes beyond that by stating irreversibility, specifying exactly what related data is destroyed, and detailing the confirmationToken requirement with the preview-then-confirm sequence. It does not restate the idempotency or openWorld hints, but adds real operational 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?

Three dense sentences, no filler. The destructive/irreversible nature and the pause alternative are front-loaded before the procedural confirmation requirement, which matches how an agent should reason about the call.

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 mutation's scope, irreversibility, alternative, and the required precondition. Minor gap: organizationId/projectId/requestId semantics are absent and must be inferred, but nothing blocks a correct call.

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

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

Schema coverage is 0%, so the description must carry the load. It explains confirmationToken semantics (must come from preview_operation with matching tool and arguments) and implies the 100-item cap on trackedQueryIds. organizationId, projectId, and requestId are left unexplained, but the two non-obvious parameters are handled.

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 blast radius (captured answers, matches, metrics history) and a hard cap (up to 100). Clearly distinguishable from update_tracked_queries and delete_cluster among siblings.

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

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

Explicitly names the alternative for a non-destructive path (pause with update_tracked_queries) and the condition that selects it. Also spells out the mandatory confirmation workflow via preview_operation, which is the key routing decision an agent must make.

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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the aggregation grain (one row per cluster) and an error-relevant constraint (dates must fall inside the data retention window), which an agent needs to avoid a failed call.

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

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

Two sentences, front-loaded with what the tool returns before describing use cases. The example questions add value rather than filler, though the sentence is a bit dense with enumerated fields.

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 re-explained, and the tool's aggregation and date constraint are covered. However, half the parameters remain semantically undefined in both schema and description, which leaves gaps 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 38% across 8 parameters. The description adds only the date-window/retention constraint; it says nothing about organizationId, projectId, dateFrom/dateTo formats, or includeUngroupedQueries, which are undocumented in the schema too. It 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 (rank-tracking metrics), resource (keyword clusters), scope (per project, date window), and the row shape (positions, share of voice, sentiment). This clearly distinguishes it from siblings like get_sentiment_breakdown, get_share_of_voice_formula, and list_clusters.

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

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

Gives concrete usage context via example questions ('which clusters are strongest or weakest', 'niche vs generic queries') and a prerequisite (dates must fall within the retention window). It does not explicitly name which sibling to use instead when the agent wants per-query or time-series detail, so it falls short of full routing 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 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-structured behavior: the terminal states to poll for, the polling interval, and that the result only appears once completed. That is strong added context, though it does not discuss failure payloads or error handling.

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, zero filler: identity plus origin tools first, then the actionable polling protocol. Every clause earns its place and the critical timing guidance 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-value detail is not the description's job, and the annotations cover the safety profile. What remains — what the tool returns conceptually, which jobs it serves, and how to poll them — is fully 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%, so the description must carry parameter meaning, and it only partially does — it implies jobId originates from one of the listed starter tools but never describes the jobId/organizationId format or scoping. The parameter names are largely self-explanatory, so a minimum-viable 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?

Names a specific verb+resource ('status and ... result of a background job') and enumerates the exact producer tools (discover_brands, suggest_brand_names, discover_keywords, discover_prompts, start_auto_clustering) that create such jobs. An agent can distinguish this poller from all other get_* siblings without opening a schema.

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

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

Explicit when-to-use cadence ('poll it every few seconds until status is "completed" or "failed"') plus an explicit when-not instruction ('do not start the job again while it is pending or running'). Both the loop condition and the anti-pattern are stated, 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 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds the key behavioral constraint that it takes NO date window and is a current-state snapshot, plus it discloses the return shape (one row per brand + org aggregate). It does not mention pagination or result limits, but with annotations and an output schema present, this is a meaningful add.

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 metric list, then scoping constraint, then the alternative-routing sentence. Dense but every sentence earns its place; slightly long metric enumeration keeps it from 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?

Given an output schema exists (so return shape need not be re-explained) and a single obvious required param, the description covers purpose, scope, metric semantics, and alternative routing. An agent has everything needed to select and 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?

Only one parameter (organizationId) at 0% schema description coverage, so the schema says nothing about it. The description does not explain what organizationId accepts (format, source), but for a single obvious required id the gap is minor. Baseline 3 for a low-coverage single-param tool where the description adds no syntax.

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 (organization-wide brand rank-health board), enumerates the exact metrics returned (share of voice, mention rate, average mention position, positivity, tracked-query count), and states the row granularity (one row per brand). It distinguishes itself from siblings by naming get_project_rank_tracking_stats as the date-ranged alternative.

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

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

Explicit when-to-use (company-wide snapshot, no date window) and when-not (date-ranged comparison), naming the alternative tool and the workflow (call per-project tools for each project id returned here). It even provides a routing example 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?

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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond the annotations: the data-retention constraint on dates and the scope of the aggregated return content. It says nothing about permissions or rate limits, so not a 5.

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

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

Front-loads the resource and its output set, then immediately gives routing guidance and a hard constraint. Every sentence carries information; even the sample-questions line earns its place by clarifying the analytical intent.

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, yet the description still summarizes them helpfully. Purpose, routing and the retention constraint are all covered; the main gap is parameter-level detail, which is only partly mitigated by the 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 description coverage is only 38%; engines, countries and queryClusterIds are documented in-schema, while projectId, organizationId, dateFrom/dateTo and includeUngroupedQueries are bare. The description adds the 'date window' framing and the retention-window constraint that governs the date params, but does not compensate for the undocumented identity and ungrouped-query 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?

Names a specific verb+resource ('Aggregated rank-tracking summary for a project') and enumerates the concrete outputs (average positions, share of voice, sentiment split, mention/SERP/shopping rates, position-distribution buckets). It explicitly positions itself as the project overview, distinguishing it from the per-cluster and time-series siblings.

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

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

Explicitly says 'prefer it before the per-cluster or time-series tools', which routes the agent relative to get_cluster_breakdown and get_rank_tracking_time_series, and the sample questions clarify intent. It stops short of stating when NOT to use this tool (e.g. when a drill-down is required instead), so it is strong context without full when/when-not framing.

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 declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: a data retention window constraint on dates, the response-size tradeoff tied to granularity, and the optional per-competitor lines.

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

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

Three front-loaded sentences with no padding: the core purpose leads, followed by granularity advice and example questions. Efficient, though the example question list borders on decorative.

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 retention window plus granularity advice cover the main pitfalls. Still, for a 10-parameter tool at 40% schema coverage, the absence of any mention of countries, clusters or ungrouped-query semantics leaves real gaps.

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

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

Schema description coverage is only 40%, so the description must compensate, and it partially does by explaining granularity, the date window, competitor series, and engine splitting. It remains silent on countries, queryClusterIds, includeUngroupedQueries and the required org/project identifiers, leaving half the parameters to raw schema inference.

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: a time series of rank-tracking metrics scoped to a project and bucketed by granularity. This clearly separates it from the per-query sibling get_tracked_query_time_series, though it never names that sibling explicitly, so the differentiation is inferred rather than stated.

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

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

Offers useful guidance on granularity ('prefer weekly or monthly for long windows') and frames use cases ('what changed in my AI visibility', 'share-of-voice trend split by engine'). However, it gives no explicit when-to-use/when-not rules against siblings like get_project_rank_tracking_stats or get_tracked_query_time_series.

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 a genuinely useful behavioral constraint: dates must fall within the data retention window. It also discloses granularity (per engine, per competitor), though it says nothing about pagination or result size.

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 capability, then routing, then constraints. Slightly padded by the two example questions that restate the tone/sentiment guidance, but overall tight and purposeful.

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 annotations cover safety. However, for an 8-parameter tool with 38% schema coverage, several parameters (cluster IDs, ungrouped inclusion, countries) are never addressed, leaving gaps an agent must guess at.

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

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

Schema coverage is only 38%, so the description must compensate, and it largely does not. It implies date-window and engine/competitor scoping but never explains queryClusterIds, includeUngroupedQueries, or how countries interact with the breakdown. The undocumented parameters remain 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?

States a specific verb+resource: positive/neutral/negative sentiment split of AI mentions, scoped by date window, AI engine and competitor. It explicitly 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 (tone/sentiment questions) plus two named alternatives with the conditions that select them. Example questions ('is anything negative being said', 'how positive is my coverage') anchor the intent concretely.

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.

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context: date format (YYYY-MM-DD, inclusive), the row-level granularity (one row per tracked query text across engine and country variants), and the set of metrics returned (share of voice, positivity, mention, link, search, shopping positions). This goes beyond basic annotation coverage.

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

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

The description is concise, front-loading the output format (one row per tracked query), followed by metrics, filtering, and sorting. It is well-structured and avoids extraneous text. Could be slightly improved by explicitly stating the required 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?

Given the tool's complexity (16 parameters, no schema descriptions) and the presence of an output schema (which we do not evaluate), the description adequately covers the output format and basic filtering/sorting. However, it does not fully compensate for the lack of parameter descriptions or provide enough guidance on pagination and the meaning of specific sort fields.

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 mentions filtering by engine, country, cluster, status, check frequency, passes, or text, and sorting by any metric. However, it does not explain the meaning of parameters like limit, offset, includeUngroupedQueries, or the individual sortBy enum values. The baseline of 3 applies.

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

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

The description clearly defines what the tool does: it's the keyword-level view of a project, one row per tracked query, with metric positions. It distinguishes itself from the detailed time-series and sample tools. However, it does not explicitly contrast itself with the sibling tool search_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?

The description states the date range and filtering capabilities, which imply when this tool is useful (overview of keyword performance). However, it does not explicitly tell the agent when to use this tool versus the sibling search_tracked_queries, or versus time-series tools.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the description's added value is the permissions requirement ("Owners only"), the ordering guarantee, and the important warning that the returned "id" rather than "userId" is what update_member consumes. That last point is a genuine behavioral gotcha not derivable from annotations or schema.

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

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

Two dense sentences with no filler: the first covers scope, ordering, fields and the optional flag; the second covers the permission gate and the id-vs-userId caveat. Information is front-loaded and 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?

An output schema exists, so return values need not be spelled out, yet the description still usefully characterizes them (ordering, role, state). With annotations handling the safety profile and the description covering permissions and the id caveat, the main remaining gap is pagination semantics for 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 0%, so the description must carry the param burden, yet it only covers includeInvitations ("optionally also its pending invitations") and implies organizationId. The limit and offset pagination parameters are never explained in prose, leaving half the inputs undocumented beyond raw schema constraints.

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?

It names the resource (organization members) and specifies the shape of the result: ordering (oldest first), fields (role, state), and the optional inclusion of pending invitations. It also links to update_member, so an agent can place it among siblings, though it doesn't contrast with the other list_* tools explicitly.

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

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

"Owners only, as in the web app" gives a real eligibility precondition, and the update_member reference implies a follow-up workflow. However, there is no when-to-use/when-not guidance or named alternative for listing members versus other membership-related tools like invite_member or cancel_invitation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the useful workflow fact that the output feeds all other tools. It does not describe the return shape, but an output schema exists to carry 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?

Two sentences, no filler. The prerequisite instruction is front-loaded in the second sentence and follows directly from the stated scope in the first.

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 zero-parameter, read-only listing tool with annotations covering safety and an output schema covering return values, the description supplies exactly the missing piece an agent needs: when to call it and what its output enables.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the baseline of 4 applies. The description correctly conveys that no filtering arguments are accepted ('every organization the caller belongs to').

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 two resources (organizations and their active projects), with the scope constrained to those the caller belongs to. This clearly separates it from siblings like get_organization, get_project, or list_members.

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 instructs 'Call this FIRST' and explains why: the returned (organizationId, projectId) pairs are prerequisites for every other tool. That is unambiguous sequencing guidance with a stated rationale, not an implied convention.

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