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

Annotations provide no read-only or idempotent hints, so the description carries the full burden of behavior disclosure. It details the re-read logic, the contract enforcement (preview is a contract, not a suggestion), the stale and uncertain states, the locking behavior, and the immediate update of the stored campaign list. This is exemplary transparency that goes far beyond the sparse annotations.

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

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

The description is dense but each sentence carries essential information. It is front-loaded with the core purpose and exclusivity, then progressively explains the state machine, error handling, and post-conditions. No word is wasted, and the structure logically guides the reader from purpose to usage to edge cases.

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

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

Given the complexity of the operation (state transitions, contract enforcement, locking, and resolution), the description covers all critical aspects: preconditions, stale handling, uncertain outcome and its implication, resolution path, and immediate data consistency update. It also references resolveAdChange, ensuring the agent knows the follow-up action. Nothing essential is missing for correct invocation.

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

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

The only parameter, id, has a schema description ('Id of the change request.') that is 100% covered. The description adds semantic meaning by specifying that the id must refer to an approved and non-expired change request, and that the request's state will transition based on the operation. This goes beyond the schema's basic description, providing context on what the id represents in the workflow.

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 opens with a specific verb and resource: 'Apply an approved change at the advertising platform.' It also states it is 'The only call that changes anything at the platform,' clearly distinguishing it from siblings like previewAdChange, approveAdChange, and rejectAdChange. The purpose is unambiguous and contextually rich.

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

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

It explicitly states the precondition: only for a request that is 'approved' and not expired. It further explains when the operation will not proceed (stale request) and that an uncertain outcome keeps the campaign locked until resolveAdChange is called. This gives clear guidance on when and how to use the tool, and implicitly when not to (e.g., unapproved or expired requests).

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

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

Discloses important behavioral details beyond the annotations: it records approval with its origin, enforces the previewed/expiry constraint, and clarifies the distinction between approval and actual platform mutation. No contradiction with annotations is present.

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 organized with a clear purpose statement followed by constraints and clarifications. It is slightly verbose with repeated emphasis, but all sentences contribute useful information and the structure is easy to parse.

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 single-parameter input and absence of an output schema, the description provides sufficient context: valid states, error condition, and the relationship to applyAdChange. It does not describe success response details, but that is not required by the schema setup.

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 only parameter, 'id', has a basic description ('Id of the change request') and schema coverage is 100%. The description does not add additional detail about the id format, scope, or validation, so the semantics are adequate but not enriched.

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?

Clearly states the tool approves a previewed change, with the verb 'approve' and object 'ad change'. It is well distinguished from sibling tools such as applyAdChange, rejectAdChange, and previewAdChange.

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 defines when approval is valid (state 'previewed' and not expired), states a key restriction (API keys cannot self-approve, resulting in 403), and clarifies that approval does not apply the change to the platform—that is applyAdChange's role.

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 discloses some behaviors: accounts that fail are not assigned and are listed in 'nicht_eingerichtet', a 409 response occurs when an org connection already exists, and the 'ersetzen' flag can overwrite. However, side effects on existing connections and the full response structure are not explained.

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 verbose, repetitive, and unstructured. It uses a single long paragraph with convoluted phrasing (e.g., 'half an assignment sends into the void and nobody sees why') and mixes German terms, making it hard to parse quickly.

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

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

No output schema is provided, and the description does not explain the response format or how it fits with sibling tools beyond vague references. It omits details about authentication, error handling for standard cases, and the relationship to connection inventory and configuration.

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 input schema only contains 'type' and 'projectId', but the description refers to multiple parameters not present in the schema ('ebene', 'umfang', 'konten', 'nicht_eingerichtet', 'ersetzen'). This mismatch severely confuses parameter handling and adds no meaningful detail about the actual schema fields.

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

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

The description states a general purpose ('Decide where the credentials live and which accounts this project feeds') but uses cryptic, non-standard terminology (e.g., 'ebene', 'umfang', 'konten') without explicitly naming the operation as assigning connection targets. It does not clearly differentiate from related tools like autoconfigureConnection or enableConnection.

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 references autoconfigureConnection and getConnectionInventory but does not explicitly state when this tool should be used instead of those alternatives. It implies batch/org-level assignment but lacks clear conditional guidance or a 'when not to use' note.

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 indicate non-read-only and non-idempotent behavior, and the description aligns by noting that the connection shows as connected after approval. No contradictions, and it adds context about side effects without being redundant.

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 slightly longer than necessary but includes essential details (return field, user interaction, validity, next steps, error code) in a logical flow. No fluff, but 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?

Given the simple output (an authorize_url), the description covers the return value and a potential error (503). It does not specify other error cases, but that is acceptable for a tool of this simplicity.

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?

Both parameters have meaningful descriptions, including the list of valid platform values and a note that openai_ads uses a different tool (setConnectionBearerKey). Schema coverage is 100%.

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?

Clearly states it returns an authorization URL for connecting an ad platform to a project, and distinguishes from org-level and API-key alternatives.

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?

Explains that the URL must be opened by a human in a browser, mentions no headless method, and provides follow-up actions (autoconfigureConnection or getConnectionInventory). Could more explicitly contrast with similar sibling tools like authorizeOrgConnection, but the guidance is clear for typical usage.

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 provide only basic hints (readOnlyHint false, idempotentHint false, destructiveHint false), so the description carries the full burden of behavioral disclosure. It adds crucial details: the link requires human browser action, expires in ten minutes, is restricted to owners, and returns 503 when the platform is not enabled. These are exactly the behavioral nuances an agent needs and are not covered by annotations.

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

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

The description is tight and efficient, delivering the primary purpose, the contrast with the sibling, and all operational constraints in three sentences. The core action is front-loaded, and every sentence adds value without fluff. It is exemplary in structure.

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 one-parameter tool with no output schema, the description covers all necessary aspects: what it does, when to use it, how to use it (human opens link), validity, permissions, and an error condition. An agent has everything needed to invoke it correctly and interpret the outcome, so nothing essential 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?

The schema already fully documents the single 'type' parameter with a description (coverage 100%), so the description doesn't need to add parameter-level detail. The description does provide context about the ad platform, but it doesn't elaborate on the parameter's format or values beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Get the link that connects an ad platform for the whole organisation' – a specific verb and resource. It immediately distinguishes itself from the sibling authorizeConnection by explaining the org-level scope and inheritance. This leaves no ambiguity about what the tool does.

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

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

It explicitly names the alternative (authorizeConnection) and explains the difference: the resulting connection belongs to the organisation and is inherited by all projects. It also provides concrete usage constraints: a person must open the link, it is valid for ten minutes, owners only, and a 503 error occurs if the platform is not enabled. This fully informs when to use this tool vs. its sibling and what to expect.

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 discloses that the tool may create entities ('everything found or created') and explains the state machine (fertig, auswahl, manuell) and the need to call again with 'auswahl' to select a candidate. Since annotations only give false for read-only/idempotent/destructive, the description carries the burden and provides useful behavioral insight.

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 a single long, run-on paragraph with em dashes and parenthetical asides. It contains redundant phrasing (e.g., the explanation of 'auswahl' and the trailing 'for pick another account'). It could be better structured and more concise.

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 there is no output schema, the description adequately explains the three possible response states and the follow-up action for 'auswahl'. It covers the main flow but lacks details on error cases or edge conditions, so it is not 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?

The schema already describes type and projectId clearly. The description adds context about the flow but also references parameters ('auswahl', 'neu_waehlen') that are not part of the current input schema, which may confuse. It adds some value but not a great deal beyond 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 clearly states that the tool lets Trackdolphin pick an account, property, pixel, or conversion action, and explains the three possible outcomes. It is a specific action on a specific resource and is distinguishable from other connection-related 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?

The description notes that it should be used after the user has authorized, and references saveConnectionConfig as an alternative for the 'manuell' case. This gives some guidance on when to use the tool, though it could be more explicit about when to prefer it over other configuration 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 declare destructiveHint=true and idempotentHint=true. The description adds the valuable behavioral detail that cancellation is possible 'until the last second before execution,' which is not covered by annotations. It doesn't describe side effects, but for a simple cancel operation the annotations carry the safety profile and the description adds timing 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?

The description is two short sentences (one in English, one in German) with zero fluff. The core action is front-loaded, and the timing constraint is included without padding. Every word earns its place.

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

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

For a zero-parameter tool with no output schema, the description fully covers what an agent needs: the action, the target, and the timing constraint. There are no missing details that would prevent correct invocation. The sibling set further clarifies its role in the deletion workflow.

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?

There are zero parameters, so the baseline is 4. The description doesn't need to explain any parameters, and the schema is empty. No additional parameter information is required or expected.

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 ('cancel') and resource ('pending deletion request'), clearly distinguishing it from sibling tools like requestAccountDeletion (which creates) and getAccountDeletionStatus (which reads). The German phrase reinforces the exact action. An agent can immediately understand what this tool does without ambiguity.

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

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

The description implies when to use it: when a deletion is pending and you want to cancel it. It adds the timing constraint 'possible until the last second before execution,' which clarifies the valid window. It doesn't explicitly name alternatives, but the context is clear enough that an agent would know this is the cancellation action, distinct from requesting or checking status.

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 indicate readOnly=false, idempotent=false, destructive=false, which are minimal. The description adds substantial behavioral detail: immediate effect without merchant confirmation, access remains until end of paid period, no pro-rata credit, and that a missing subscription is not an error with the cancelled flag set to false. It also names the underlying API method (appSubscriptionCancel). This fully compensates for the sparse annotations and does not contradict them.

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

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

The description is a compact paragraph that front-loads the core action and then lists consequences. It mixes English and German, which slightly reduces clarity, but every sentence conveys meaningful information with no filler. It is appropriately sized for the tool's complexity.

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

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

For a single-parameter tool with no output schema, the description covers the critical behavioral aspects: immediate effect, access continuity, no proration, and edge-case handling (no active subscription). It also references the exact API call. Nothing essential for an agent 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?

The schema has one parameter (projectId) with a description ('Kennung des Projekts'), giving 100% schema description coverage. The description does not add any additional parameter-specific context or explain how to obtain projectId, so the schema already carries the meaning. Baseline of 3 is appropriate because the description adds nothing beyond 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 clearly states the tool cancels the Shopify subscription, using a specific verb and resource, and details the effect (sets plan to free). It distinguishes itself from sibling tools like getShopifySubscription and createShopifySubscription by its action, even without naming them. No tautology or ambiguity.

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

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

The description implies the use case (cancelling a subscription) but does not explicitly contrast with alternatives like getShopifySubscription or createShopifySubscription. It provides some contextual guidance (immediate effect, no merchant confirmation, no proration, and behavior when no subscription exists) but stops short of explicit when-to-use vs. when-not-to-use guidance. Score 3 reflects implied usage without explicit 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?

The description thoroughly discloses side effects: it sends the change to the platform, records a ledger entry, reads back the value, and details idempotency behavior (same key returns entry without sending), conflict detection (different values with same key gives 409), and the refusal of new changes when an outcome is open. It also explains the approval exception and statuses, providing comprehensive behavioral transparency.

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 dense but well-organized, front-loading the core purpose and then covering exceptions and edge cases in a logical flow. It is a single paragraph but each sentence builds on the previous, avoiding unnecessary repetition while still conveying all critical information. Slightly long but not verbose.

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

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

The description covers the full context needed to use the tool correctly: the primary action, idempotency guarantees, conflict handling, open outcome refusal, the approval exception, and the meaning of the returned statuses and fields. It even names the ledger entry fields and statuses, making the behavior complete even without an 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?

Although the input schema is empty, the description adds meaning by explicitly mentioning the behavior of `idempotency_key` and how it interacts with the change values. However, it does not enumerate the actual parameters for the change payload (e.g., campaign ID, fields to update), leaving some parameter semantics implicit. Given the empty schema, the description adds substantial value, but not exhaustive.

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

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

The description clearly states the verb ('Change'), the resource ('a campaign at the advertising platform'), and positions it as the primary method for changing campaigns. It explicitly distinguishes it from sibling tools like approveAdChange and applyAdChange, making the tool's purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: it says not to call approveAdChange or applyAdChange after using this tool, except in the specific case of require_approval, where those follow-ups are required. It also explains what happens with idempotency keys and open outcomes, giving clear usage 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?

The description discloses that rules are combined with AND and that the response includes the cohort and current person count, adding behavioral context beyond the annotations. However, it does not explain side effects like persistence or require authentication. The annotations already indicate it is not read-only, so the description adds some value but not extensive behavioral detail.

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

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

The description is a single, dense sentence that front-loads the action and then lists rule types and response. It packs a lot of information efficiently without excessive verbosity. The structure is acceptable, though the long list could be broken into separate sentences 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?

The schema is minimal (only projectId), and there is no output schema. The description compensates by explaining the rule types and response, but it does not specify the format for passing parameters (e.g., JSON structure for event_types, traits), nor whether name is a required parameter. The mismatch between the description and the actual input schema creates ambiguity, making the description incomplete for an agent to reliably call the tool.

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

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

The schema only lists projectId, while the description details many other parameters (name, purchases_min, revenue_min, etc.) and explains their meanings. This is valuable because the schema coverage is 0%, but the mismatch between the schema and the description could confuse an agent about how to pass these parameters. The description provides semantics but not syntax or required/optional status beyond 'all rules optional'.

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

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

The description clearly states the verb 'Create a cohort' and specifies the resource (cohort) and the action (creating with name and rules). It lists the rule types, which helps distinguish it from sibling tools like cohort_update or cohort_delete. The purpose is unambiguous, though it doesn't explicitly contrast with siblings beyond the verb.

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 does not provide any guidance on when to use this tool versus alternatives such as cohort_update, cohort_preview, or cohort_export. It mentions that all rules are optional, which is a parameter guideline, but not about selection. There is no 'when not to use' or mention of 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?

The description transparently discloses the key side effect that deleting the cohort does not delete the underlying people or events. Combined with the destructive and idempotent annotations, an agent understands exactly what will and will not happen.

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 a single sentence that front-loads the action and then provides a brief side-effect clarification. It is concise and well-structured, though the bilingual text is slightly redundant.

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

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

The description gives enough context for the tool's core purpose and side effects. It does not mention prerequisites or error conditions, but given the simplicity of a delete operation and the presence of sibling tools, this is largely sufficient. The lack of parameter explanations is a minor 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?

The schema provides no descriptions for the id and projectId parameters, and the description does not clarify their meanings or constraints. While the names are somewhat self-explanatory, the lack of any explicit explanation leaves room for ambiguity.

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

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

The description clearly states the tool deletes a cohort and explicitly clarifies that underlying people and events are unaffected, which precisely distinguishes it from sibling tools like cohort_create, cohort_update, and cohorts_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?

The description does not explicitly say when to use this tool over alternatives, but the action is unambiguous and the sibling list makes the use case obvious. The note that underlying data remains unaffected provides helpful guidance for decision-making.

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 this as read-only and idempotent. The description adds valuable behavioral detail about SHA-256 hashing, no plaintext output, and the specific phone number formats for Meta vs Google, which goes beyond the annotation metadata.

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 somewhat redundant, repeating the no-plaintext and hashing points in both English and German. It is still reasonably concise but could be tightened while preserving the important details.

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?

There is no output schema, and the description only vaguely indicates a CSV file or JSON response. It does not specify the response structure, error behavior, or required parameter meanings, so an agent lacks enough information for robust invocation.

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

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

Only the 'format' parameter is described. The required 'id' and 'projectId' parameters have no schema description and are not mentioned in the description, leaving most parameters 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 clearly states the tool exports a cohort as a customer list, using a specific verb and resource. It also explains the purpose of the hashed columns, making the tool's function unambiguous.

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

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

The description explains the output format (CSV vs JSON) but does not explicitly say when to choose this tool over sibling tools like cohort_preview or cohorts_list. Context implies export use, but no direct alternative guidance is provided.

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

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

The annotation already indicates read-only, idempotent, and non-destructive behavior, and the description reinforces this by framing the tool as a preview. It also discloses a key output behavior (truncated email hashes). No side effects are described, but the annotations cover that aspect adequately.

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 and well-structured, providing the essential purpose and key output details in a single sentence. It avoids unnecessary verbosity while covering the most important behavioral aspects.

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

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

The description gives useful output context but omits parameter explanations and explicit usage boundaries. Given the low schema coverage and no output schema, a bit more detail about the meaning of 'id' and 'projectId' would make the tool self-contained. Still, for a simple preview operation, the core behavior is adequately conveyed.

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 schema has zero description coverage for the two parameters, and the description does not explain what 'id' or 'projectId' refer to. While the names are somewhat self-explanatory in context, 'id' is ambiguous and could refer to a cohort ID, rule ID, or other entity without explicit documentation.

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

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

The description clearly states the tool's purpose: previewing a cohort by showing the number of matching persons and up to ten examples sorted by revenue. It also specifies that email hashes are truncated, removing ambiguity about the output. The name and description distinguish it from sibling tools like cohorts_list and cohort_export.

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 implies when to use the tool (when you need a quick preview of cohort membership), but it does not explicitly state when not to use it or contrast it with alternatives such as cohort_export or cohorts_list. Usage guidance is mostly inferable from the verb 'preview' and the output details.

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 useful behavior beyond annotations: the count is recalculated per request and can be null when the evaluation is unreachable. This is valuable runtime behavior an agent needs to interpret results correctly. No contradiction with annotations.

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

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

Two concise sentences, front-loaded with purpose. Every sentence earns its place: the first states what is returned, the second clarifies the dynamic count behavior. No filler or redundancy.

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

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

For a simple read-only list tool with one fully documented parameter and no output schema, the description covers the essential return content (cohorts, rules, person counts) and flags the nullable count edge case. Minor gap: it doesn't enumerate exact fields returned, but with no output schema the description does the job adequately.

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

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

Schema coverage is 100% — the single projectId parameter is fully documented in the schema with a concrete example. The description adds no parameter-specific detail beyond what the schema provides, so the baseline 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 states a specific resource ('Cohorts of a project') and clearly describes what is returned: saved cohorts with their rules and current person counts. It's clear and distinguishable from the sibling cohort tools (cohort_create/update/delete/preview/export) by the verb 'list' in the name plus the explicit content. Not a 5 because it doesn't explicitly name the sibling it differs from.

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

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

No guidance is given on when to use this tool versus alternatives. It does not mention that cohort_create/update/delete exist for mutations, nor does it give conditions for when listing is appropriate. The behavioral note about the count being recalculated is informative but not usage 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 mark it as non-read-only, idempotent, and non-destructive; description adds that it replaces the cohort's name and rules, which is concrete behavioral context beyond the annotations. It does not mention auth or side effects, but annotations lower the bar.

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?

Single sentence, front-loaded with the action and object, with no filler or redundant elaboration.

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?

Although low-complexity and no output schema, it omits how new name/rules are passed given the schema only lists id/projectId, and it provides no usage context or prerequisites. This leaves the agent with an incomplete call contract.

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?

Input schema describes only id; projectId is undocumented in both schema and description. The description mentions replacing name/rules, but the schema exposes no parameters for supplying them, so it does not clarify parameter meaning and may confuse.

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 explicit action 'Change' plus target 'cohort', and the German clause clarifies exactly what is altered ('Ersetzt Name und Regeln'). This distinguishes it from sibling create/delete/list/export/preview cohort 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?

No explicit statement of when to use this over cohort_create/cohort_delete/cohort_preview or any prerequisites (e.g., cohort must already exist). Only inference from the verb 'Change'.

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 discloses a critical behavioral detail: the plaintext key is returned only once and is never retrievable afterwards, even by the system. This is not present in the annotations and provides essential transparency about the operation's side effects.

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, consisting of two sentences, and is bilingual but compact. It front-loads the purpose and adds essential behavioral information without unnecessary fluff.

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

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

For a creation tool with no output schema, the description adequately covers the core behavior, including the one-time return. It does not mention error conditions or authentication requirements, but these are likely assumed in the broader API context.

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 input schema has zero parameters, so the baseline score of 4 applies. The description does not reference any parameters because there are none, which is consistent.

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

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

The description clearly states the action (create an API key) and specifies the intended use cases (MCP server, command line, scripts), distinguishing it from listApiKeys and revokeApiKey by implying creation of a new key.

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 implies when to use this tool (for non-browser access) but does not explicitly contrast it with listing or revoking keys. The context is clear enough for an agent to decide, but explicit alternatives are not named.

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 are all false, so the description carries the behavioral disclosure. It states that the tool returns a URL and that it may return an honest message instead when prerequisites are missing. It also clarifies it does not render invoices itself, adding meaningful context beyond the basic annotation flags.

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

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

Concise and front-loaded with the primary action. Each sentence serves a purpose: stating the function, distinguishing from custom rendering, and noting failure modes. No fluff or redundancy.

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

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

For a zero-parameter tool with no output schema and minimal annotations, the description covers the essential behaviors: what it does, what it returns, when it fails, and how it differs from related tools. It is complete enough for an agent to decide when to invoke it and what outcome to expect.

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?

There are zero parameters, so the baseline is 4. The description adds context about implicit prerequisites (existence of a Stripe customer and Stripe configuration) which is relevant for the agent even though there are no explicit 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?

The description clearly states the action (create a Stripe customer portal session) and the resource (Stripe customer portal), and specifies what it returns (URL). It also differentiates from related tools by noting it is Stripe's surface for invoices, payment methods, and cancellation, and explicitly excludes custom invoice rendering.

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 context on when to use the tool (for Stripe-hosted customer portal) and when not (if custom invoice rendering is needed). It also outlines failure conditions (no Stripe customer or no Stripe setup) which guides an agent on when not to expect a URL. It does not name specific sibling tools, but the exclusion and scenario details are sufficient.

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 discloses side effects (creates a Stripe session) and edge-case behavior (25+ projects returns contact request, Stripe not set up returns message instead of error). This goes beyond the annotations, which already indicate a mutation (readOnly=false).

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

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

The description is concise and well-structured: it opens with the primary action, then elaborates on quantity rules and exception handling. No redundant or vague statements.

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

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

The description covers the main outcome (payment URL) and exceptions, but does not specify the exact response format or error codes. Since no output schema is provided, the description gives enough context for an agent to understand what to expect.

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

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

The tool has no parameters, so the baseline of 4 applies. The description does not need to explain any input fields, and none are omitted.

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

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

The description clearly states the tool's purpose: creating a Stripe checkout session for a volume plan change and returning the payment URL. It distinguishes itself from billing portal operations like createBillingPortalSession by focusing on the checkout flow.

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 implies when to use the tool (starting a plan change to the volume plan) and includes specific conditions (e.g., for 26+ projects no list price, returns contact request). It does not explicitly name alternative tools, but the context is sufficient for an agent to decide.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses that it returns an ingest key, normalizes domains (removes schema and www), rejects duplicate domains in the same organisation, and increases the subscription count. This gives an agent concrete expectations about side effects and constraints.

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 verbose and bilingual, repeating the same core action in English and German ('Create a project' / 'Legt ein weiteres Projekt an'). It includes extraneous promotional phrases like 'ohne Klickstrecke' and 'Abo-Menge' that do not aid tool invocation. It is front-loaded with the primary action but could be trimmed.

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 creation tool with no input schema and no output schema, the description covers the essential behavior: what it creates, what it returns (ingest key), constraints (domain normalization, duplicate rejection), and a side effect (subscription increase). It does not specify error handling or authentication, but these are not expected given the minimal schema and the operation type.

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

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

The tool has zero parameters and the input schema is empty, so the baseline is 4. The description does not need to elaborate on parameters, though it mentions domain handling which implies an implicit input that is not reflected in the schema – this is a minor mismatch but does not affect scoring since there are no formal 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?

The description opens with a clear verb+resource: 'Create a project in the organisation'. It distinguishes this from all sibling tools because it is the only creation tool among many listing/reading tools. The bilingual phrasing adds context but the intent is unambiguous.

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

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

The description states a use case ('Damit lässt sich ein Onboarding vollständig über die Schnittstelle fahren') and implies this is the programmatic path for onboarding. It does not explicitly name an alternative tool or a 'when not to use', but as the sole create operation, the guidance is clear enough.

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 discloses the asynchronous plan activation via webhook, the dev-store test subscription with no money, and the intentional prevention of duplicate subscriptions. These behaviors are not captured by the annotations (readOnly=false, idempotent=false, destructive=false) and add essential 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?

The description is dense but efficient, front-loading the core action and then covering edge cases (dev store, already active) and a critical usage requirement (target _top). Each sentence adds value without redundancy.

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

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

The description covers the full lifecycle: creation, confirmation flow, dev-store behavior, duplicate prevention, and the top-window requirement. It even explains the return values (confirmation_url, already_aktiv) despite no output schema, making it complete for correct invocation.

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

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

The only parameter, projectId, is already fully described in the schema (100% coverage). The tool description does not add further semantics for this simple identifier, so the baseline 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 states a specific action (start a Shopify subscription via the Billing API) and the key output (confirmation_url), clearly distinguishing it from sibling tools like getShopifySubscription and cancelShopifySubscription. The verb and resource are unambiguous.

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

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

It explains when the tool should be used (starting a subscription), what happens if a subscription already exists (returns already_aktiv=true, no URL), and provides a critical usage instruction (open URL in top window, target _top). This gives clear contextual guidance beyond the schema.

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 indicate destructiveHint=true and idempotentHint=true, so the description adds value by specifying that it deletes encrypted tokens and the exact error scenario. It does not contradict annotations; it enriches them with concrete consequences and edge-case 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 tightly packed sentences: the first defines the primary action and effect, the second gives the alternative and a key error. No filler, all information is relevant and 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?

The description covers the essential operational context: the destructive nature, the alternative tool, the intended scenario, and a distinguishing error. Given the schema fully documents parameters and there is no output schema to describe, nothing critical is missing for an agent to invoke this correctly.

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

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

Schema description coverage is 100%, and the schema already thoroughly describes both parameters, especially 'type' with a detailed list of accepted values and connection methods. The description adds no additional parameter-specific guidance, so it meets the baseline for high coverage without extra explanation.

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

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

The description clearly states the tool's function: 'Disconnect a platform from this project' and 'Deletes the row including the encrypted tokens'. It distinguishes itself from siblings like disableConnection and deleteOrgConnection by specifying the exact operation and scope (project-level, full deletion with tokens).

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

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

Explicitly provides an alternative: 'Use disableConnection instead when sending should only pause.' It also specifies the ideal use case ('for accounts that were revoked at the provider or changed hands') and an error condition (409 when connection belongs to organisation), giving clear guidance on when to invoke this tool versus others.

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 indicate destructive and non-read-only behavior. The description adds valuable context: it deletes encrypted tokens and reports affected_projects, and it states the permission restriction. It does not contradict the annotations and enriches the safety picture beyond what structured data provides.

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

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

Three sentences, front-loaded with the main action, and each sentence adds essential information: the operation, the consequence on projects, and the permission. No fluff or redundancy.

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

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

While it covers the destructive effect and permission, it omits the required parameter explanation and provides only partial response details (affected_projects). Since there is no output schema, the description should describe the full return value, but it only mentions one field. The missing parameter documentation is a significant completeness failure.

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 only parameter 'type' is completely undocumented in both the schema and the description. Schema coverage is 0%, and the description never mentions what 'type' should be (e.g., platform identifier). The agent has no way to know what value to pass, making this a critical 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 clearly states the action: 'Disconnect a platform from the organisation' and specifies the deletion of the row including encrypted tokens. It differentiates from disableOrgConnection by highlighting permanent deletion, making the purpose unambiguous.

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

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

It mentions the permission requirement ('Owners only') and the effect on projects, which gives context. However, it does not explicitly contrast with alternatives like disableOrgConnection or explain when to choose deletion over disabling. The usage 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=false and idempotentHint=false, indicating mutation. The description adds valuable behavioral context: it saves a result directly to the project, and it conditionally does nothing on unclear findings ('wird nichts geändert'). This goes beyond the annotations by explaining the conditional behavior and the safety stance of preferring to ask over guessing. It doesn't contradict any 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?

The description is two sentences, front-loaded with the core purpose, and efficiently conveys the key differences from the sibling tool and the conditional behavior. No filler words; every sentence earns its place.

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

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

For a tool with one simple parameter and no output schema, the description covers the essential action, the condition for inaction, and the distinction from its sibling. It doesn't describe return values or error handling, but these are less critical given the tool's simplicity. The description is sufficiently complete for an agent 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?

The schema has one parameter, projectId, with no description coverage (0%). The description does not explain the parameter, but the name is self-explanatory as a project identifier. Since there is no schema description, the description should ideally compensate, but the single obvious parameter reduces the need. A score of 3 is appropriate because it doesn't add meaning beyond the parameter name, which is clear on its own.

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

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

The description clearly states the action: 'Detect the project platform and save it' — a specific verb and resource. It also distinguishes itself from the sibling detectProjectPlatform by noting it saves the result and checks the project's domain. This makes the tool's purpose unambiguous and differentiates it from its nearest 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?

The description explicitly references detectProjectPlatform and explains the difference (this one saves), giving context for when to choose this tool. It also includes a critical usage guideline: 'Bei unklarem Befund wird nichts geändert, lieber weiter fragen als falsch raten' — when findings are unclear, the tool does nothing and suggests asking rather than guessing. This provides clear when-to-use and when-not-to-use guidance, though it could be even more 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 provide no read-only or idempotent hints, so the description carries the full burden. It discloses that the tool fetches pages (network activity), infers the platform, and returns 'unknown' on ambiguity, warning about false guesses. This adds meaningful behavioral context beyond annotations, though it does not mention error handling for unreachable addresses.

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 a single, well-structured sentence that covers the method, expected outputs, and fallback behavior without any fluff. It is appropriately sized and 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?

While the description explains the detection method and outputs, it omits details such as the exact output format (since there is no output schema), how the address is determined, and error scenarios. This leaves some gaps for an agent relying solely on the description.

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?

There are zero parameters, so the baseline is 4. The description mentions 'an address' but does not explain where it comes from given the empty schema, which could be a source of confusion. However, since there are no params to document, the description adequately compensates.

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

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

The description clearly states the tool detects the project platform by fetching pages and inferring from known paths, listing specific systems. However, it does not differentiate from the sibling detectAndSaveProjectPlatform, so it lacks explicit sibling differentiation.

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

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

No guidance is given on when to use this tool versus detectAndSaveProjectPlatform. The description implies usage for detection but provides no exclusions or alternatives, leaving the agent to infer the distinction.

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 annotations, the description discloses that credentials are preserved, events are queued and delivered upon re-enablement, and that a 409 is returned for inherited connections, providing clear side-effect and error 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?

The description is concise, uses three focused sentences covering purpose, behavior, and error condition, with no redundant 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?

Given the simple two-parameter interface and absence of output schema, the description fully explains the tool's effect, side effects, and edge case (409), making it complete for correct usage.

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?

Both parameters (type and projectId) have schema descriptions covering 100% of params, but the tool description adds no additional meaning beyond what the schema already provides; baseline 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 states the tool pauses sending to a platform (specific verb 'Pause' and resource 'connection'), and distinguishes it from sibling tools like enableConnection and deleteConnection by noting it keeps credentials and holds events.

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 implies when to use this tool (temporary pause) by contrasting with resuming via enableConnection, and mentions a 409 error for inherited connections, but does not explicitly name alternatives or state 'use this instead of deleteConnection'.

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 readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds substantial behavior beyond that: it affects every inheriting project, holds events back until re-enabled, and preserves credentials. The 'credentials stay' note confirms the destructiveHint=false annotation, and no claim contradicts 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?

Compact and front-loaded with the primary action, using em-dash clauses that each carry distinct information (scope, effect, credential behavior, permission). Slightly dense punctuation, but no wasted words.

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?

Behavioral consequences are thoroughly covered, but for a mutation tool with no output schema and no annotations describing the response, the description should explain what type expects and what the call returns. The unexplained sole parameter is a significant gap for an agent needing 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?

There is one required parameter, type, with 0% schema description coverage, and the description never explains what type should contain or which values are valid. The only field mentioned, affected_projects, is a return value, not a parameter. The description fails to compensate for the schema gap entirely.

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 ('Pause') and resource ('organisation connection'), and the clause 'Affects every project inheriting it' distinguishes it from its sibling disableConnection, which targets a project connection. An agent can tell this apart from enableOrgConnection and deleteOrgConnection without inspecting 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?

The description implies usage context: pause (vs. delete, which removes, and enable, which resumes) via 'until it is enabled again' and 'credentials stay', and the 'Owners only' restriction gives a permission gate. It does not explicitly name the alternative tools or state when not to use it, but the contrast is reasonably inferable.

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 destructiveHint and idempotentHint annotations, the description details exactly what is removed (webhooks, pixel, token) and what remains (app installed but inert). It also discloses a specific error condition (503 without SHOPIFY_API_KEY/SECRET), offering rich behavioral context.

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

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

Two sentences deliver the action, scope, and error condition without redundancy. The description is front-loaded with the primary purpose and each sentence adds value.

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

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

For a single-parameter tool with no output schema, the description fully covers what the tool does, the resulting state, and a failure condition. An agent has all necessary information to decide and invoke 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?

The description does not elaborate on the projectId parameter, but the schema already provides a clear description ('Kennung des Projekts') with 100% coverage. No additional parameter meaning is needed, so 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 states the specific action: disconnects Shopify by removing webhooks and web pixel and deleting the access token. It also clarifies the app remains installed but non-functional, which distinguishes it from related tools like cancelShopifySubscription or getShopifyConnection.

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 provides clear context on when to use this tool (to disable the Shopify integration without uninstalling the app) and implies the alternative of full uninstall by noting the app remains. However, it does not explicitly name alternative tools or give '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 this as a mutating, non-idempotent, non-destructive operation. The description adds meaningful behavioral context: it delivers held-back events and specifies 404/409 error scenarios. It doesn't contradict annotations and goes beyond them by explaining side effects and error handling, though it doesn't cover potential edge cases like partial delivery or idempotency consequences.

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

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

Two sentences with zero redundancy. The core purpose is front-loaded, and the error/alternative guidance follows immediately. Every word earns its place.

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

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

For a simple 2-parameter mutation tool with well-documented schema, the description covers purpose, usage conditions, error cases, and alternative. No output schema exists and none is needed. The only minor gap is the lack of an explicit statement about prerequisites (e.g., connection must exist), but that's implied by the error responses. Overall, complete enough for correct invocation.

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

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

Schema coverage is 100%: both parameters are described, with type listing valid platforms and connection method. The description adds no parameter-specific details beyond the schema, so the baseline of 3 applies—the schema does the heavy lifting.

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

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

The description clearly states a specific verb and resource: 'Resume sending to a paused platform.' It distinguishes itself from the sibling enableOrgConnection by explicitly naming the condition for each error case (404 vs 409), so an agent can confidently pick this tool for project-owned connections.

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 explicitly says when to use the tool (resume a paused platform) and when not to, routing the agent to enableOrgConnection for inherited connections and noting the error responses that indicate those conditions. This is direct, unambiguous 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?

With annotations providing no hints (readOnlyHint, idempotentHint, destructiveHint all false), the description carries the behavioral disclosure burden. It discloses that the action affects all inheriting projects, that held events are delivered upon resume, and that it is restricted to owners. These are meaningful behavioral details beyond the bare annotations, though it omits idempotency and reversibility.

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 compact—a single sentence with em dashes that front-loads the core purpose. It packs multiple pieces of context (scope, side effect, permission) without bloat. It could be structured more cleanly, but it is appropriately sized and efficient.

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

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

For a mutation tool with no output schema and one undocumented parameter, the description is incomplete. It covers side effects and permissions but entirely omits any explanation of the 'type' parameter, which is required. An agent would struggle to call it correctly without additional knowledge.

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 single required parameter 'type' (string) is entirely undocumented. Schema description coverage is 0%, and the description never mentions the parameter, leaving the agent without any clue about what value to supply. The description fails to compensate for the schema gap, making this the weakest dimension.

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

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

The description clearly states the action 'Resume an organisation connection' with a specific verb and resource. The mention of 'Affects every project inheriting it' and the explicit 'organisation' qualifier distinguishes it from the sibling 'enableConnection' tool, which presumably handles non-org connections.

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 implies usage for resuming an org connection after it was disabled, and it notes the scope ('affects every project inheriting it') and permission ('Owners only'). It doesn't explicitly name alternatives or state when not to use it, but the 'organisation' qualifier and side-effect context give adequate guidance for a typical agent.

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?

Adds behavioral details beyond the readOnly/idempotent annotations: non-owners receive a 403, and the deletion date is always seven days after the request. These are useful runtime behaviors not captured by 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?

A single, front-loaded sentence that names the resource and what it returns. The German phrasing is slightly dense but still concise and to the point.

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

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

For a simple getter with no parameters, no output schema, and annotations already covering safety, the description provides the essential details: the returned status fields and the 403 condition. Nothing critical 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?

The tool has zero parameters, so the schema is trivially covered. Per rubric, a zero-parameter tool gets a baseline of 4; the description adds no parameter-specific information because there are none.

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

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

States the exact purpose: returns deletion status of the organisation, including whether a deletion is requested, since when, and the target date (seven days after request). The name and description together clearly distinguish it from sibling tools like requestAccountDeletion and cancelAccountDeletion, which are action-oriented rather than status 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?

Implies usage as a status check but does not explicitly contrast with the request/cancel deletion siblings. It does note an access restriction (only for owners, others get 403), which is a usage constraint but not guidance on selecting this tool over 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 destructiveHint false, covering safety. The description adds significant behavioral context: that expired previews are reported as 'expired' even if the background run hasn't caught up, and the business rule that old previews must not take effect. This goes beyond the annotations, though it doesn't cover other behaviors like error handling or pagination.

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

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

Two sentences with no redundancy. The first sentence states the core purpose, and the second adds a crucial edge-case behavior. Both are front-loaded and every word earns its place.

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

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

With no output schema, the description reasonably covers what the tool returns: state and platform response. It also explains the expiry behavior. It could be more explicit about the exact structure of the state, but the description is adequate for an agent to invoke and interpret the result.

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

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

The schema already fully describes the id parameter, including its source (from previewAdChange). Schema description coverage is 100%, so the baseline is 3. The description does not add further parameter-specific information, so no bonus is warranted.

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

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

The description clearly states the tool returns the current state of a single change request, including the recorded platform response. It distinguishes from listAdChanges (which lists) and other mutation tools. The phrasing 'State of one change request' is specific and uses an implicit verb that matches the name.

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

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

The description does not explicitly state when to use this over alternatives, but it provides a key behavioral nuance about expired previews that is relevant for decision-making (e.g., checking status before approval). It implies this is the correct tool for retrieving current state, though it doesn't explicitly exclude other tools like approveAdChange or rejectAdChange.

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, but the description adds substantial behavioral context: numbers are exactly as reported (no recalculations), amounts are micros of account currency, conversions may be fractional and null vs zero, data comes from the database (never live), and every row includes source and synced_at. This far exceeds what annotations provide and fully discloses data semantics.

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 long but every sentence earns its place. It is front-loaded with the core purpose, then dives into necessary details about data provenance, currency, null handling, defaults, and refresh alternatives. No fluff; each clause clarifies a behavior an agent would otherwise have to infer.

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 six optional parameters and no output schema, the description compensates by explaining the return structure (source, synced_at, per-row currency, fractional conversions, null handling) and default behaviors. An agent has all information needed to call the tool correctly and interpret results without additional lookups.

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?

Although schema coverage is 100%, the description adds meaningful semantics beyond the schema: defaults for to/from, granularity=total sums per campaign and leaves day null, ad_account_id refers to listAdAccounts (not platform id), campaign_id from listCampaigns.external_id, and the platform enum is explained with an example. This enriches the agent's understanding of each parameter.

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

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

The description states a precise purpose: returning platform metrics per campaign and day, as last synced. It distinguishes itself from siblings like syncAdAccount (live fetch) and clearly scopes what it does and does not do (no recalculation, no currency conversion, no cross-account totals). An agent can confidently select this tool for read-only metric queries.

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

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

It explicitly states the default behavior without parameters (last 30 days across all ad accounts), explains the effect of granularity=total, and points to syncAdAccount as the alternative for live data. This gives clear when-to-use and when-not-to-use guidance beyond any sibling descriptions.

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. The description adds useful context about the returned data (e.g., pricing tiers, event counting) without contradicting the annotations. It does not introduce any unexpected side effects.

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 moderately concise, providing essential details in a few sentences. It is somewhat verbose with repetition (e.g., pricing and event counting explained twice in slightly different terms), but it is not overly long and each sentence adds 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?

The description thoroughly explains what the tool returns: plan, usage limits, pricing per project, discount tiers, event counting rules, and status indicators. This gives an agent full context of the expected output, even without a separate 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?

The tool has no parameters, so schema coverage is trivially 100%. The description does not need to explain parameters, and none are referenced, making this a non-issue.

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

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

The description clearly states that the tool provides the plan and usage of the organisation, detailing pricing, events, and status. It is unambiguous that this is a billing/usage read operation.

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

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

The description implies the tool is used to retrieve current billing status and usage details, which is clear from context. However, it does not explicitly mention when to use it over alternative tools, but given the lack of parameters and the read-only nature, the intended usage is evident.

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 and idempotentHint=true, so safety is covered. The description adds that the tool returns actual data (accounts, campaigns, pixels, properties), which is useful. However, it does not describe pagination, error handling, or the exact structure of the returned data. It adds some value beyond annotations but not deeply.

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

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

The description is two sentences long and front-loads the core purpose in the first sentence. The second sentence explains the benefit. It is concise and free of fluff, though the German phrasing is slightly awkward.

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

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

For a simple get operation with two required parameters, the description is reasonably complete: it states what the tool returns and its intended use. However, there is no output schema, and the description does not detail the exact return format (e.g., nested structure, field names). It also references 'the list' without naming listChannelPulls, which could confuse an agent unfamiliar with the domain.

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

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

Schema description coverage is 0%, and the description does not mention the parameters (projectId, pullId) at all. The agent must infer their purpose from the names alone. For a tool with undocumented parameters, the description should compensate, but it provides no parameter-specific 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?

The description states the tool retrieves a single pull with its data, specifically including fetched accounts, campaigns, pixels, and properties. It distinguishes itself from the list tool by mentioning 'Wie die Liste, zusätzlich mit data', implying it is the detailed variant of a list operation. The purpose is clear, though it could be more explicit in naming the sibling tool.

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 explains a concrete use case: pre-filling target configuration so the customer doesn't have to type identifiers. This implies when to use the tool, but it does not explicitly state when not to use it or compare with alternatives beyond the vague 'Wie die Liste' reference. More direct guidance would be better.

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. The description adds genuine value beyond that by disclosing 404 (platform without account picker) and 409 (fetch still running or platform not connected) error behaviors and describing the 'ebene' / 'belegt_von' fields. No contradiction with annotations.

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

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

The description is a single dense run-on paragraph with nested parentheticals, making it hard to scan. Key facts like error codes and fields are packed into one long sentence rather than front-loaded or structured, hurting 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?

With no output schema, the description carries the burden of describing return values, and it does cover the per-account entries and error cases. Coverage is adequate but the disorganized style makes it harder to absorb, and it never names sibling tools for comparison.

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 100% and both parameters (type, projectId) are already documented in the schema. The description does not add syntax or semantics for the parameters beyond what the schema provides, so 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 states the tool lists reachable accounts for an authorization and who already uses them, with a clear post-OAuth context. It is specific about verb and resource, but the purpose is buried in a run-on sentence and never names a sibling tool it differs from, so differentiation is implicit rather than explicit.

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

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

It gives a concrete usage context ('Everything the screen after the OAuth return needs'), which implies when to call it. However, it never states exclusions or names alternatives such as listOrgConnections, getOrgConnectionMap, or listAdAccounts, so routing among 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?

Beyond the annotations (read-only, idempotent, non-destructive), the description reveals that the tool also returns actually received event types from the last 30 days and explains why this matters (typos can silently create new event types). This adds useful context about the returned data and its significance, going beyond the basic annotation flags.

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

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

The description is relatively short and to the point, with two sentences. The first sentence states the main purpose, and the second adds a reason why the recent event types are included. It is slightly verbose with the explanation about typos, but it remains concise and well-structured, with no redundant 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?

The description covers the main functionality—retrieving routing rules, defaults, and recent event types—and even explains the rationale for the latter. However, it does not mention any output format, error conditions, or how the projectId parameter is used. Given that there is no output schema, some aspects are left to inference, but the core purpose is adequately 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?

The only parameter, projectId, is not described in the schema (coverage 0%) and the tool description does not mention it at all. The name 'projectId' is fairly self-explanatory as an identifier for a project, but since the description provides no additional context about its role or format, it does not compensate for the lack of schema documentation.

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

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

The description clearly states what the tool does: it shows which events go to which destination, including current rules, defaults, and recent event types. This distinguishes it from the sibling saveEventRouting, which modifies routing. However, it does not use a standard verb like 'get' or 'retrieve', but the name and content make the purpose unambiguous.

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

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

The description implies the tool is for retrieving routing information, but it does not explicitly state when to use it or contrast it with alternatives. There is no direct guidance on when to prefer this over saveEventRouting or other read-only project tools. The purpose is clear enough to infer usage, but explicit guidance is missing.

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 valuable context about the response: it mentions the fields `import` (null if never run) and `pending` (indicating whether to keep polling), which goes beyond the annotations and helps the agent understand the tool's 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?

The description is not concise, mixing English and German awkwardly and containing a typo ('und , sobald fertig'). It front-loads the purpose but then adds details in German that may be less accessible. It is two sentences but could be streamlined and made language-consistent.

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

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

The description covers the main response content: status, UI sentence, per-day findings with recommendations, and the `import`/`pending` fields. However, it does not explain the output structure or format (since there is no output schema), nor does it differentiate from the sibling getProjectImportStatus, leaving some contextual ambiguity.

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 schema has 0% description coverage for the single required parameter `projectId`. The tool description does not mention the parameter at all, failing to compensate for the lack of schema documentation. The agent must infer that `projectId` refers to the project identifier, but no confirmation or additional context is provided.

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

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

The description states the tool returns status and findings of the last import, which is clear enough for a basic understanding. However, it does not explicitly differentiate from the sibling tool getProjectImportStatus, and the term 'findings' is vague. The mixed English/German text may also reduce clarity for non-German-speaking agents.

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

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

No guidance is given on when to use this tool versus alternatives like getProjectImportStatus or startGtmImport. The description mentions that `pending` indicates if further polling is needed, but it does not state conditions for choosing this tool over others, nor does it provide exclusions or 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 and idempotentHint, so the description does not need to repeat safety. It adds valuable behavioral detail: the `audit` field is null if the domain has never been scanned, and it explains the tool's role in generating permanent report addresses. This goes beyond the annotations and helps the agent understand return semantics.

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

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

The description is two short sentences, front-loads the primary purpose, and adds the null condition. There is no fluff or repetition. It is efficiently written and easy to parse.

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 no parameters, no output schema, and annotations covering safety, the description provides the essential behavior (latest scan, null when never scanned) and a use case. However, it lacks explicit differentiation from the sibling 'getTrackingAudit' and does not specify what the audit object contains. These gaps are minor but prevent a perfect score.

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?

There are no parameters, so schema coverage is trivially 100%. The description mentions 'for a domain' but does not explain how the domain is determined (likely from current context). With zero parameters, the description carries the burden of clarifying implicit inputs, and it leaves this ambiguous, so it does not fully compensate.

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

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

The description clearly states the tool retrieves the latest scan/audit for a domain, and even specifies the null case. It implies a 'get' operation on a resource (domain's latest audit). However, it does not explicitly differentiate itself from the sibling tool 'getTrackingAudit', which likely fetches a specific audit, so the purpose is clear but not sharply distinguished.

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 mentions a use case ('basis for permanent report addresses') which gives context, but it does not explicitly state when to prefer this tool over alternatives like 'getTrackingAudit' or 'startTrackingAudit'. There is no direct comparison or exclusion, 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=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by detailing the output structure: it explains that projects without assignments are included with konto_id: null, and that completeness is indicated by 'vollstaendig' with 'fehlt' for missing items. This gives the agent a clear picture of what to expect without contradicting the annotations.

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

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

The description is well-structured: it opens with the core question, then details the row structure, and ends with the special case of unassigned projects. It is informative without being excessively verbose, though a bit long. Every sentence contributes meaning, and the key point about null konto_id is front-loaded in the final 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 read-only tool with no parameters and no output schema, the description fully explains what the agent will receive: the exact fields per row, the inclusion of unassigned projects, and the naming conventions for completeness. There is nothing missing that an agent needs to understand the tool's behavior or interpret the response 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?

The tool has zero parameters and schema coverage is trivially 100%. Since there are no parameters to document, the baseline score of 4 applies. The description does not need to explain parameters, and it appropriately focuses on output semantics.

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

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

The description clearly states the tool's purpose: mapping projects to advertising accounts, with one row per project and platform. It specifies the output content including credential level, account name, hint, primary flag, and completeness status. While it does not explicitly differentiate from sibling tools like listOrgConnections, the focus on the project-to-account mapping and the inclusion of unassigned projects gives it a distinct identity.

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 implies when to use the tool (when you need a project-account mapping with completeness details), but it does not explicitly state alternatives or when not to use it. There is no guidance about choosing this over listOrgConnections or getConnectionInventory, leaving the agent to infer context from sibling names.

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 indicate readOnly, idempotent, and non-destructive behavior. The description adds no further behavioral details or side-effect warnings, but it does not contradict the annotations.

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

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

The description is a single concise sentence that conveys the core purpose and key data dimensions without unnecessary detail 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?

There is no output schema and no description of the return structure, and parameter semantics are missing. The description communicates the general content but leaves important invocation and response details unspecified.

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

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

The schema provides no descriptions for projectId or days, and the description does not explain the meaning or format of either parameter. 'days' is especially ambiguous with no indication of lookback window or accepted values.

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?

Description clearly identifies the tool as returning the most active channels, with traffic sources, events, purchases, and revenue per channel. The resource (channels for a project) is unambiguous and distinct from sibling tools like top pages or funnels.

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

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

No explicit guidance is given about when to use this tool versus alternatives such as getProjectKpis, getProjectTopPages, or getProjectDailySeries. The description implies channel-level analysis but does not state when it should be preferred.

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 it read-only, idempotent, and non-destructive; the description adds that it returns received events per day, but does not disclose potential limitations like date ranges, pagination, or data availability.

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?

Extremely concise: two short clauses convey the resource, metric, and typical use case without filler.

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

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

With no output schema, the description gives a high-level idea (daily event counts and trend anomalies) but omits output shape, units, and period details; acceptable for a simple read-only series yet not 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?

The schema already documents the optional 'days' parameter (default 14), but the description adds no further meaning for either parameter and leaves 'projectId' semantics implicit.

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?

Clearly identifies a read-only time series of received events per day and highlights its purpose of surfacing dips and outliers. It is specific enough to distinguish from general project metrics tools, though it does not explicitly name alternatives.

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

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

The description implies a monitoring/analysis use case but provides no explicit guidance on when to choose this tool over sibling metrics or tracking-health tools, and no when-not-to-use conditions.

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 context about the purpose (detecting missing event types) but does not disclose additional behavioral traits such as pagination, response format, or edge cases. Given the annotations, a 3 is appropriate as the description adds some value but not rich behavioral detail.

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

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

The description is two sentences, front-loaded with the main purpose and a concrete use case. It is concise and to the point, with no wasted words. However, it could be slightly more structured by adding parameter guidance without becoming verbose.

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 two parameters and no output schema, the description is incomplete. It does not clarify the meaning of 'days', does not specify the return format (e.g., a mapping of event type to count), and does not mention any filtering or pagination behavior. The agent would need to infer or guess at critical invocation details.

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 for parameter documentation. However, it does not mention projectId or days at all. While projectId is inferable from the tool name, the meaning of days (likely a lookback window) is unexplained. The description adds no parameter semantics, leaving the agent without guidance on how to populate these fields.

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

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

The description clearly states the tool returns event types with their occurrence counts ('Wie oft jede Event-Art vorkam') and gives a specific use case for detecting missing event types. It is specific about the resource (events by type) and the output (frequencies), though it does not explicitly differentiate from sibling tools like getProjectKpis or getProjectDailySeries.

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 provides a clear use case: checking if an event type is completely missing, e.g., due to a non-working hook. This implies when to use it, but it does not mention alternatives or exclusions, leaving the agent to infer that it is the right tool for event-type frequency analysis.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the funnel concept and drop-off focus, which is useful context beyond the annotations, but it doesn't disclose any additional behavioral traits such as defaults for the optional days parameter or any limitations.

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 a single concise sentence with no fluff. It front-loads the core concept (purchase funnel) and immediately describes the value. There is no unnecessary repetition or padding, making it easy to parse.

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 no output schema and low schema coverage, the description should compensate by explaining parameters and expected results. It explains the funnel concept but omits any detail about the optional days parameter, how to interpret the output, or any edge cases. An agent calling this tool would not know what to expect in the response or how to set parameters 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%, so the description must compensate by explaining parameters. It mentions the funnel stages (product view, cart, purchase) but does not clarify what projectId or days mean, nor does it explain how days affects the result. The description adds almost no parameter-specific meaning beyond the schema's bare property names.

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

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

The description clearly states the tool's purpose: a purchase funnel showing visitor progression from product view to cart to purchase and drop-off points. It is specific to a project (implied by projectId). However, it doesn't distinguish itself from sibling tools like getProjectKpis or getProjectDailySeries, so the differentiation is weak.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any exclusions, prerequisites, or alternative tools. An agent is left to infer that this is for funnel analysis, but there is no explicit context or routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about what the tool reports (current import, past imports, missed orders), which is useful but does not disclose any additional behavioral traits like pagination, limits, or response format. Given the annotations, this is adequate.

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

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

The description is a single sentence, front-loaded with the core purpose ('Import status and match rate') followed by a clarifying German phrase. It is concise with no wasted words, though the German phrase might be slightly redundant for an English-speaking agent.

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

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

For a simple read-only tool with one parameter and no output schema, the description is mostly adequate. It explains what the tool returns but omits usage guidance and parameter details. Given the annotations cover safety, the missing pieces are not critical but do leave some ambiguity.

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 schema has one parameter, projectId, with zero description coverage. The tool description does not explain what projectId refers to or how it should be formatted. Although the parameter name is self-explanatory, the description fails to compensate for the lack of schema documentation, leaving the agent to infer its 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?

The description states the resource ('Import status and match rate') and the specific information it provides (current import running, past results, missed orders). It is specific enough to distinguish from startProjectImport, but it does not explicitly differentiate from other status tools like getGtmImport, which also reports on import status.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention that this is for project imports specifically, nor does it contrast with startProjectImport or getGtmImport. The agent must infer usage from the name and description alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context beyond annotations by specifying the exact data scope and time ranges returned, which helps the agent understand the nature of the response. It does not contradict annotations and adds meaningful information about what the tool reveals.

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

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

The description is two sentences with zero filler. The first sentence lists the concrete key figures, and the second provides a quick use-case. It is front-loaded with the most important information and remains compact, making it easy for an agent to parse quickly.

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

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

The tool is simple (one required parameter) and has no output schema, so the description carries the burden of explaining return values. It lists the metrics and timeframes, which is sufficient for an agent to know what to expect, though it does not specify the exact JSON shape. Given the simplicity and the presence of sibling tools with overlapping purposes, this description is adequately complete for a quick status check.

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

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

Schema coverage is 100%, and the schema already documents projectId with a clear description and example. The tool description does not add anything about the parameter beyond mentioning 'project' generically. Since the schema handles parameter semantics, a baseline score of 3 is appropriate — no additional value is provided by the description here.

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 ('project') and specifies exact metrics: events from the last 24 hours, purchases and revenue from the last 7 days, and delivery rate to advertising platforms. It also conveys a clear purpose ('fastest answer to is tracking running?'), which distinguishes it from broader tools like getProjectTrackingHealth or getTrackingAudit without needing to open 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?

The description implies when to use it via the phrase 'Die schnellste Antwort auf „läuft das Tracking?“' — indicating it is a quick health check. However, it does not explicitly mention alternatives or when not to use it, such as when a deeper audit (getTrackingAudit) or daily series (getProjectDailySeries) is needed. The usage context is implied rather than explicitly contrasted with siblings.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat them. The description adds no extra behavioral details (e.g., rate limits, side effects) and does not contradict the annotations.

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

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

The description is extremely concise, a single sentence that conveys the core purpose without superfluous words or repetition. It is well-structured and front-loaded with the key concept.

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 simplicity of a read-only getter, the description gives enough context for basic usage. However, there is no output schema provided and no mention of the response format, which leaves some ambiguity about what exactly is returned. It is adequate but not 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?

The only parameter, projectId, has no description in the schema and the description does not mention it. The tool name and context imply it identifies the project, but no explicit semantics are provided. Schema coverage is 0%, and the description fails to compensate.

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

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

The description clearly states the tool retrieves onboarding/setup progress, listing completed steps, the next step, and their benefits. It answers the specific question 'where does this project stand?', which distinguishes it from more generic setup tools like getProjectSetup, though not explicitly naming alternatives.

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 provides context on when to use it (to understand project onboarding progress) and what question it answers, but it does not explicitly mention when not to use it or how it differs from similar tools like getProjectSetup. No alternatives are named.

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 and idempotentHint, so the tool is known to be safe. The description adds value by specifying what data is returned (collector address, event counts, timestamps, last event type), which is useful behavioral context beyond the annotations. No contradictions with annotations.

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

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

The description is somewhat verbose and includes extra context about where the returned value should be placed (environment or plugin), which is useful but not essential for tool invocation. It is structured as a single sentence but could be more concise and front-loaded with the core purpose.

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

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

For a simple read-only tool with one parameter, the description adequately explains the return data (collector address, event counts, first/last event, last seen type). No output schema is needed since the description clarifies the response content. It is sufficiently complete for an agent to know what to expect.

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

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

With schema description coverage at 0%, the description must compensate for undocumented parameters, but it does not mention projectId at all. The single required parameter is implied by the tool name and context, but the description lacks explicit guidance on its format or purpose, leaving the agent to infer from the schema alone.

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

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

The description clearly states the tool returns the collector address and event verification details (count, first/last event, last seen type). It distinguishes the purpose from routing or channel tools by focusing on setup and endpoint info, though it does not explicitly name sibling alternatives.

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

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

The description implies usage when you need the endpoint configuration for the SDK, mentioning where the value should be placed (environment or plugin). However, it does not explicitly state when to use this tool versus others or provide exclusion conditions, so guidance is only implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds context that the result includes purchases and revenue, which is useful. However, it does not disclose behavioral details like pagination, default time ranges, or sorting, so it adds moderate 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?

The description is a single concise sentence in German. It is short and front-loads the core purpose. While it could be more informative, it has no fluff or redundancy, making it appropriately concise for its length.

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

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

Given there is no output schema and three parameters with zero explanation, the description is incomplete. It does not specify return format, default values, or how the parameters affect results. For a read tool, more context is needed to ensure correct invocation, especially around the 'days' and 'limit' parameters.

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

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

Schema description coverage is 0%, and the description does not mention any of the three parameters (days, limit, projectId). With zero coverage, the description must compensate by explaining parameter meaning, but it does not. The agent has no information about what these parameters do or their formats.

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

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

The description clearly states the tool returns top pages along with their associated purchases and revenue. It specifies the resource (top pages) and the data included, making the purpose understandable. However, it does not differentiate this from sibling tools like getProjectKpis or getProjectDailySeries, so it lacks explicit sibling differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention context, prerequisites, or exclusions. The agent is left to infer usage from the name and description alone, which is insufficient given the large set of sibling 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 declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds valuable context about the silent nature of tracking failures ('the page keeps running, only the measurement not') and enumerates what the tool returns. This goes beyond the structured fields and helps the agent understand the tool's purpose without contradiction.

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

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

The description is two sentences, front-loaded with the core question, and includes a helpful analogy about silent failures. No fluff, but it could be slightly more structured with bullet points. Efficient for the information it conveys.

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

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

For a simple read-only health check with one param and no output schema, the description explains the purpose and the key data points returned. It doesn't specify the response format, but that's not critical given the annotations and simplicity. The description is sufficiently complete for an agent to understand when and how to invoke 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 has one required parameter (projectId) with 0% description coverage. The description does not explain the parameter at all. Since schema coverage is low, the description should compensate, but it doesn't. However, projectId is a common identifier and the tool name makes it clear, so the gap is not severe.

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

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

The description clearly states the tool answers 'is something broken right now?' and lists the specific data points it returns (open disruptions, last check, last event). It is distinct from siblings like getTrackingAudit, though it doesn't explicitly name alternatives. The verb 'get' plus resource 'project tracking health' is specific.

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

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

The usage is implied: use this when you need tracking health status. However, it provides no explicit when-to-use or when-not-to-use guidance, and doesn't mention alternatives like getLatestTrackingAudit. The context about silent failures hints at a scenario, but no direct 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by explaining the meaning of `configured: false` and listing the data returned (connected, since when, webhooks, web pixels), which goes beyond the annotations. No contradiction.

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

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

The description is two sentences long, front-loaded with the main purpose, and includes a valuable clarification about the `configured` field. Every sentence earns its place; there is no redundant 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?

Given the tool's simplicity (one parameter, read-only, no output schema), the description adequately explains the return content (connection status, timing, webhooks, web pixels) and the meaning of a key field. It does not mention error conditions or additional context, but these are not critical for a status check tool with strong annotations.

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 input schema has one parameter, `projectId`, with a description ('Kennung des Projekts'), so schema coverage is 100%. The tool description does not add any additional parameter context, such as format or examples. Baseline 3 applies because the schema fully documents the parameter.

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

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

The description clearly states it returns the status of the Shopify connection, including whether a store is connected, since when, which webhooks and web pixels the app created. It also explains the meaning of the `configured: false` field. This is a specific verb-resource combination and distinguishes it from sibling tools like `disconnectShopify` or `getShopifySubscription`.

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 implies the tool is for checking connection status, but it does not explicitly state when to use it versus alternatives, nor does it provide exclusions or conditions. It is clear enough for the agent to infer, but lacks explicit routing guidance compared to better examples.

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, so the safety profile is covered. The description adds critical behavioral details beyond annotations: it queries Shopify live, falls back to the last seen status with 'aktuell' set to false if Shopify is unreachable, and specifies exact HTTP error responses (403 for Stripe, 404 for no store). This is valuable context that annotations do not provide.

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

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

The description is a single, well-structured sentence that front-loads the primary purpose and output fields, then provides source, fallback behavior, and error conditions. Every sentence earns its place with no redundancy or filler. The information is dense but efficiently organized.

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 has one parameter, no output schema, and annotations covering safety, the description is remarkably complete. It lists all expected return fields, explains the data source and fallback, and specifies error scenarios. An agent has everything needed to call the tool correctly and interpret the response, even without an 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?

The input schema has 100% coverage for the single parameter projectId, with a description 'Kennung des Projekts' (project identifier). The tool description adds no further detail about the parameter's format or semantics beyond the schema. Since the schema already documents it fully, the baseline of 3 applies; the description does not need to compensate.

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 ('get') and resource ('Shopify billing status of the store') and enumerates the exact fields returned (plan, status, test mode, price, trial period, end of paid period). It clearly distinguishes itself from other billing tools by specifying it queries Shopify directly rather than the internal table, and it names the error conditions for non-Shopify billing origins. This leaves no ambiguity about what the tool does.

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

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

The description explicitly states when the tool is applicable: only for accounts that bill via Shopify (billing_origin equals shopify). It gives clear exclusions: Stripe accounts get 403, projects without a Shopify store get 404. It also implies an alternative (internal billing status) by saying it queries Shopify, not the own table. This gives the agent strong guidance on when to select this tool over siblings like getBillingStatus.

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

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

The annotations already indicate readOnly, idempotent, and non-destructive behavior. The description provides some details about the response status fields and retention policy, but these describe the resource, not the tool's own side effects or operational behavior beyond what annotations cover.

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 verbose and mixes English and German, making it hard to follow. It dives into detailed response field semantics that are not relevant to the input, and could be much more concise and structured.

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

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

The description lacks critical information about the input parameter, the exact purpose, and when to use this tool. The mixed-language text and focus on response internals leave an agent without enough context 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?

The only parameter is 'id' (string) with no description in the schema or the description text. The description does not clarify what the ID refers to (e.g., audit ID, project ID), leaving the agent to guess.

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 begins with 'Status and findings of a scan' which gives a general idea, and the tool name 'getTrackingAudit' implies retrieval. However, it lacks an explicit verb like 'Retrieves' and the description is mostly about response fields, so the purpose is not crisply 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?

There is no guidance on when to use this tool versus alternatives like getLatestTrackingAudit or startTrackingAudit. The description does not mention use cases or conditions for selecting this tool.

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 indicate readOnlyHint=false, so the tool is known to be a mutation. The description goes well beyond this by detailing the email delivery, the seven-day validity, single-use link, owner-only permission, and the authentication restriction (real login, not API key). This is rich behavioral context that helps the agent anticipate side effects and constraints. No contradiction with annotations.

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

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

The description is a single sentence that is information-dense but not bloated. It leads with the primary action ('Invite a team member') and then packs in the essential constraints. It is concise and front-loaded, though the German clause structure makes it slightly less scannable for an agent. It earns a 4.

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 no parameters and no output schema, the description covers the key aspects: the action, the delivery method, the link behavior, permissions, and authentication method. It does not specify what the tool returns (e.g., success message or invitation ID), but since no output schema exists, this is not strictly required. The description is sufficiently complete for an agent to decide whether to invoke it and to understand its side effects.

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 input schema has zero parameters, so there is nothing to document. The description adds meaning beyond the empty schema by explaining the tool's purpose and behavior. Since there are no parameters, the description carries the full explanatory burden, and it does so adequately, warranting a 4 rather than the baseline 4 for zero params.

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

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

The description states the specific verb 'Invite' and resource 'team member', and explains the mechanism (email invitation with a one-time link valid for seven days). It clearly differentiates from siblings like listTeam (listing) and revokeInvitation (revoking), even without naming them, because the action and its scope are unambiguous.

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

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

The description provides clear context on when to use this tool (to invite a team member) and includes important constraints (only organization owners, only via real login, not API key). However, it does not explicitly mention alternative tools or exclusions, leaving the agent to infer that listTeam or revokeInvitation are different operations. The constraints are useful but not a full routing guide.

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 provide readOnlyHint, idempotentHint, and destructiveHint=false. The description goes beyond these by stating 'Nothing is fetched from the platform for this call', clarifying that it returns cached data. It also explains the delivery_7d metric comes from the same ledger as tracking, not a second calculation, and describes the error field semantics. There is no contradiction with annotations; in fact, it reinforces the read-only nature.

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 long but well-structured, front-loading the core purpose in the first sentence. Each subsequent sentence adds distinct information about fields, metrics, and behavior. It is dense but not redundant; however, it could be trimmed slightly without losing essential info. The structure with semicolons and clauses is clear, earning a 4.

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

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

Given the complexity (many fields, no output schema), the description is remarkably complete. It explains every field in the response (external_id, name, currency, timezone, last_synced_at, last_sync_error, is_manager, metrics_7d, metrics_30d, supports_changes, delivery_7d) and their meanings. It also clarifies the source of metrics and the relationship to changeAdCampaign. There is no output schema, so the description carries the burden, and it does so thoroughly.

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 schema has one optional parameter 'platform' with a description that is clear ('Restrict to one platform, e.g. google_ads.'). Schema description coverage is 100%, so the description adds no additional meaning to the parameter. The tool description itself does not mention the platform parameter, but it is not required to since the schema covers it adequately. 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 clearly states the tool lists advertising accounts with their sync state, and details the fields returned. It is specific about the resource (ad accounts) and distinguishes itself from siblings like listCampaigns by focusing on accounts and their sync/metrics, not campaigns. The verb 'list' plus the resource and the explicit detail about manager accounts and metrics make the purpose unambiguous.

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

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

The description explains what the tool returns and that nothing is fetched from the platform, but it does not explicitly state when to use this tool versus alternatives. There is no mention of alternatives like listCampaigns or getAdMetrics, nor any conditions like 'use this when you need account-level sync status'. The usage is implied (when you need ad accounts) but not explicitly differentiated from siblings.

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

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

It clearly describes the row contents (requested, before, after, who, approval source, platform answer) and enumerates all possible states, including edge cases like 'uncertain' and 'stale.' The explicit statement 'Nothing is fetched from the platform for this call' adds transparency beyond the readOnly 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?

The description is overly verbose and repetitive, repeating 'newest first' and 'newest 100 rows' near-identically. It includes redundant phrases like 'the same list the dashboard shows as' and lists states twice in different formalisms, making it harder to parse quickly.

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?

Even without an output schema, the description covers the return row structure and all state enumerations, which is sufficient for a consumer to understand the data shape. It also explains filtering behavior and the default limit. Minor omissions like pagination details are acceptable given the simplicity.

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

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

The description adds semantic depth to the status parameter by explaining each enum value in a parenthetical, which is not present in the schema. It also clarifies the meaning of 'direct' in the approval source context. The limit and ad_account_id descriptions from the schema are sufficient, but the status explanation enhances understanding.

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 explicitly states 'The change history of the organisation, newest first' and references the dashboard equivalent, making the tool's purpose unambiguous. It also clarifies it returns a list of changes, distinguishing it from other ad-related 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?

The description does not explicitly compare this tool to alternatives like listCampaigns or getAdChange, though it notes 'Nothing is fetched from the platform for this call,' which implies a local operation. Usage context is implied but not clearly stated for when to choose this over other list 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 declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral context: server-side search and pagination, case-insensitive matching, the limit cap of 200, offset pagination, and the total count field. It also discloses the internal-team restriction, which is valuable beyond annotations.

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

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

The description is moderately long but every sentence earns its place. It front-loads the core purpose and then packs parameter semantics and access restriction into the remaining text. The German is concise and the structure is logical, though it could be trimmed slightly without losing value.

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

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

For a read-only list tool with no output schema, the description covers the essential details: what it returns, how search and pagination work, and who may use it. It does not mention error handling or authentication, but given the annotations and the simple nature of a list operation, this is sufficient. The missing return format is implicitly covered by the field list.

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% (only 'q' has a description). The description compensates fully by explaining that 'q' performs case-insensitive substring matching on address and name, that 'limit' maxes at 200, and that 'offset' and 'total' handle pagination. This goes beyond the schema's minimal defaults and constraints, giving the agent complete parameter understanding.

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 opens with a specific verb and resource: 'List all user accounts of the platform' and enumerates the exact fields returned (email, name, organizations with role, staff right, confirmed address, creation date). It clearly distinguishes from siblings like listTeam and listApiKeys by focusing on all user accounts across all organizations.

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 explicitly states the access restriction ('Nur für das interne Team — für alle anderen gibt es diesen Endpunkt nicht.'), which is a clear when-to-use/not-use condition. It also explains the server-side search and pagination behavior, but does not name alternatives or exclusion criteria relative to other list 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 cover read-only/idempotent/non-destructive. The description adds a meaningful behavioral detail: the actual secret key is never returned, only shown during creation, which is beyond the annotation hints.

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 concise sentences with no redundant information; the limitation about the key not being included is valuable and placed upfront.

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 parameterless, read-only list operation with no output schema, the description fully covers what is returned and the key limitation. Nothing essential 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?

No parameters exist and schema coverage is 100%, so the description need not explain parameters. Baseline 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?

States the specific operation ('List API keys') and describes exactly what is returned (organization's valid keys with name, prefix, last usage), distinguishing it from siblings like createApiKey and revokeApiKey.

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?

Clearly implies usage for listing keys and explicitly notes the key itself is not shown (only at creation), guiding when not to use this tool. Stops short of explicitly naming alternative tools, but context is sufficient.

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. The description adds substantial behavioral context: it returns the last synced state, explains null vs zero budget semantics, the is_removed flag and its inclusion rule, and the meaning of metrics_7d/30d fields. No contradictions with annotations.

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

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

Though long, every sentence contributes value: purpose and scope are front-loaded, followed by key field semantics, metrics explanation, and a pointer to an alternative tool. No redundancy or filler; structured logically for an agent to parse.

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

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

With no output schema, the description must explain the returned shape. It covers campaign fields, null budget semantics, is_removed behavior, metric periods, and the distinction from getAdMetrics. An agent has enough detail to correctly interpret and use the tool's output.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds nuance by explaining that include_removed reveals otherwise hidden removed campaigns and reiterates that adAccountId is from listAdAccounts (already in schema). It goes slightly beyond the schema but is not heavily needed.

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?

Clearly states the verb and resource: lists campaigns for one ad account. It distinguishes itself from getAdMetrics by noting it returns stored state, not live data, and explicitly points to getAdMetrics for daily series. The purpose is unambiguous and separate from 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 getAdMetrics as the alternative for daily series and states it is never a live call, which implies when to use it (need stored snapshot) versus when to use syncAdAccount for fresh data. Provides clear context on its role among ad-related 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results are returned newest first and include a status plus a summary with an example, providing useful output details beyond what annotations state. It does not contradict any annotations and adds contextual behavioral information.

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

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

The description is two sentences with no unnecessary words. The first sentence front-loads the purpose and output format, while the second sentence provides usage context. It is concise and well-structured, earning a high score.

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

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

The description is sufficient for a simple read-only list operation. It mentions the output includes status and a summary, and it gives usage context (step 4 of the assistant). There is no output schema, so the description provides some indication of the response format. It could be more detailed about response fields, but it covers the essential information an agent needs to call the 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?

With schema description coverage at 0%, the description carries the burden of explaining parameters. The only parameter, projectId, is not explicitly described, but it is implied through 'this project' (dieses Projekts). Given the single, simple parameter, this is a minor gap; however, the description could have stated that projectId is the project identifier to fully compensate for the missing schema documentation.

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

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

The description explicitly states the tool lists the status of pulls for a project, newest first, with a summary like '3 campaigns, 2 conversion-actions'. It distinguishes from related siblings (startChannelPull, getChannelPull) by indicating it lists all pulls for the project rather than initiating or fetching a single pull. The bilingual phrasing is clear and unambiguous.

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

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

The description provides a specific usage context: 'Der Endpunkt, den Schritt 4 des Assistenten abfragt, solange noch etwas offen ist' (the endpoint queried by step 4 of the assistant while something is still pending). This implies when to use it but does not explicitly mention alternatives or when not to use it. The guidance is clear enough for an agent to select this tool in the given scenario.

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

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

The annotations (readOnlyHint, idempotentHint, destructiveHint) already establish the read-only, safe nature. The description adds valuable behavioral details, such as the inheritance rule and the importance of `used_by_projects` count before disconnecting, which goes beyond the basic annotations.

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

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

The description is somewhat verbose and includes cryptic phrasing ('the number that has to be on the button before anybody disconnects it'), which could be simplified for clarity. It is not overly long but could be more straightforward.

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

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

The description sufficiently explains the concept of inherited connections and the significance of the used_by_projects count. Given that there is no output schema and no parameters, this level of detail is adequate for an agent to understand what the tool does and its implications.

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

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

The tool has zero parameters, so the baseline score of 4 applies. The description does not need to explain any parameters since none exist, and it correctly focuses on the tool's behavior.

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 indicates this tool lists organisation-level platform connections, distinguishing them from project-specific ones. The verb 'list' is implied by the tool name and the context. However, the phrasing is somewhat convoluted, especially the 'button' metaphor, which slightly reduces clarity.

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 provides context about inherited connections but does not explicitly state when to use this tool versus other connection-related tools (e.g., listChannelPulls, authorizeOrgConnection). The 'readable by every member' note hints at access, but no direct alternatives or exclusions are mentioned.

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 significant behavioral context beyond the annotations: production always appears first even without events, only production is used for evaluations and delivery, and other environments are stored but never counted or reported. This discloses important quirks and operational semantics that are not inferable from the schema or annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and includes essential behavioral details. It is slightly verbose with German and English mixing, but the content is necessary and efficiently packed.

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

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

The description covers the key behaviors: the 30-day window, counters, production ordering, and counting semantics. It does not describe the return format (no output schema exists), but for a simple listing tool the description provides sufficient behavioral detail. The main gap is the undocumented parameter.

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 schema has 0% description coverage for the only parameter, projectId, and the description provides no explanation of this parameter. There is no added meaning beyond the raw schema definition, which is just a string. The description fails to compensate for the lack of parameter documentation.

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

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

The description clearly states that the tool lists environments for a project, with which environments sent events in the last 30 days and counters. It identifies the specific verb (list) and resource (environments for a project). It does not explicitly distinguish from siblings, but the resource and scope are unambiguous.

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

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

The description provides context (30-day window, production-first ordering) but gives no guidance on when to use this tool versus alternatives. No alternatives or exclusions are mentioned, so an agent has no explicit basis to prefer it over other project-related 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by clarifying access scoping (only projects the logged-in access can see), the returned identifiers, and the tool's role as the entry point for later calls. No contradiction with annotations.

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

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

The English opening and the German elaboration partly duplicate the same purpose ('List the projects' vs 'Alle Projekte ...'), creating redundancy. The useful details about IDs and first-call sequencing are present but would be stronger with tighter, non-repetitive wording.

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

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

For a parameterless, read-only list tool, the description gives the essential outcome, the returned project identifiers/fields, and the key reason to call it first. Pagination and empty-result behavior are not mentioned, but these are minor gaps for such a simple tool.

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

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

The input schema has zero parameters, so the baseline is 4. The description correctly treats project IDs as outputs needed by later calls rather than inputs, and no parameter documentation is required.

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

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

The description states a clear verb and resource: 'List the projects of the organisation', and specifies the returned fields (Kennung, Name, Projekt-System). It does not explicitly contrast with siblings like suggestProjects or createProject, but the 'Alle Projekte ... Zugriff hat' wording defines the scope well enough.

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 explicitly frames this as the first call: 'Der erste Aufruf für alles Weitere' and explains that every other query needs one of the returned project IDs. It gives clear sequencing guidance, though it does not name alternative tools or state when not to use it.

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

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

The description adds useful behavioral detail beyond the readOnly annotation by stating results are newest first and include an associated note. It does not mention pagination or response format, but the read-only nature is already covered by annotations.

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

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

The core purpose is front-loaded and the description is reasonably brief. The second sentence adds rationale for the endpoint's existence, which is somewhat useful but not strictly necessary.

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

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

For a simple, read-only, no-parameter endpoint, the description provides enough context: what is logged, the ordering, and that notes are included. It does not detail output fields, but the absence of an output schema makes this acceptable.

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?

There are no parameters, so the schema coverage is trivially complete. The description does not need to explain parameter semantics, and the baseline for zero-parameter tools 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 identifies the tool as an audit trail of console access changes, specifying who changed staff rights, when, and with what note. It is distinct from admin list and mutation tools 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?

The description implies this is the dedicated read-only endpoint for historical staff-rights changes, positioned alongside the current admin list. It does not explicitly name alternatives like listAdminUsers or setAdminUserStaff, but the context makes the intended use clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds value by disclosing what the result contains (roles, last login, invitations with expiry), which is useful context beyond the annotations. No contradiction.

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 resource is front-loaded ('Team of the organisation') followed immediately by the return content. Every word earns its place.

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

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

For a parameterless, read-only list tool with no output schema, the description is reasonably complete — it enumerates what the agent will get back (members with roles and last login, open invitations with expiry). It could mention ordering or pagination, but those are minor gaps for a simple list operation.

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

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

The tool has zero parameters, so the baseline is 4. The schema coverage is 100% trivially, and there are no parameters requiring documentation. The description appropriately focuses on return content rather than parameter semantics.

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

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

The description states a specific resource (team of the organisation) and details the content: members with role and last login, plus open invitations with expiry dates. This distinguishes it from the team-related siblings inviteTeamMember and revokeInvitation. Slight deduction because the description is written in German, which reduces accessibility for an English-speaking agent.

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

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

The usage is implied through the content description — it returns members, roles, last login, and open invitations. However, it does not explicitly state when to use this tool versus the invite/revoke siblings, nor does it name any alternatives or exclusions. Adequate but not 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=true and idempotentHint=true, so safety is covered. The description adds meaningful context by stating that the journey includes anonymous visits before the person revealed their identity, and clarifies that the key can be a customer number, full email hash, or visitor identifier. This goes beyond the annotations but doesn't describe pagination or response format, which is acceptable given the read-only nature.

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 a single, well-structured sentence that front-loads the purpose and then explains the key parameter. It is concise and contains no fluff, though the German wording is slightly dense. It earns its place with no redundant 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?

No output schema is provided, so the description should cover return behavior, but it does not describe the structure or pagination of the response. Given that it's a read-only, idempotent tool with a limit parameter, a note about pagination or response format would improve completeness. The description is adequate for basic usage but not fully complete for an agent to anticipate the response.

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 67% (key and limit have descriptions, projectId does not). The description adds significant value for the key parameter by explaining it comes from the person list and specifying the accepted identifier types (customer number, email hash, visitor identifier). This is more than the schema provides. The limit parameter is already clear from the schema, and projectId is a common identifier that doesn't need extra explanation.

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

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

The description clearly states the tool retrieves the full chronological journey of a single person, including metrics and all events, even anonymous visits before identification. It specifies the resource (one person) and the key parameter, distinguishing it from persons_list which lists persons. However, it lacks an explicit verb like 'get' or 'retrieve', so it's slightly less direct.

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