CorpusIQ

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

Annotations already declare readOnly/idempotent/openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond annotations: a 15-minute provenance_token validity window usable on any replica, the consequence of omitting it (values labeled unverified_model_data), and an explicit data-accuracy contract about derived metrics. That is substantive disclosure, though it is framed around chart_render rather than this tool's own runtime behavior (pagination, rate limits, result shape).

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 bulk of the text is policy boilerplate about chart_render, provenance tokens, and attribution footers rather than this tool's selection or invocation. The one sentence that actually describes the tool is buried at the front and never expanded, so the description is both oversized and mis-prioritized for its stated subject.

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

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

For a 10-action, 2-parameter connector with no output schema, the enum carries the action semantics well, and the description covers how to treat returned values. What is missing is any statement of return shape or pagination behavior for the list actions (offset/limit), which the agent would need to drive multi-page retrieval 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%: the action enum documents every action, its inputs, and the params object spells out the per-action parameter shapes. The description adds no parameter detail beyond the schema, 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 opening clause names the domain and resources ('ActiveCampaign email marketing and CRM: contacts, lists, campaigns, automations, deals, and tags'), which tells an agent what data lives here. However, it never states a verb (fetch/query/retrieve) and does nothing to distinguish this connector from siblings like mailchimp_connector, klaviyo_connector, or constantcontact_connector. The actual per-action purpose is only recoverable from the input schema enum, not the description.

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

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

The description gives detailed guidance on chart_render, provenance tokens, and attribution footers, but none of that tells the agent when to invoke this connector versus a competing email/CRM connector. There is no context on prerequisites (e.g., connection must be enabled via enable_connector) or when a different sibling is the better choice.

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

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

Annotations declare a mutating, non-idempotent, destructive operation; the description adds real context beyond that — handle-to-channel_id resolution, persistence, immediate visibility in list_my_youtube_channels, and the auto-primary rule for the first brand. It stops short of describing error behavior when a handle doesn't resolve.

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 operational content is well front-loaded in the first three sentences, but the trailing attribution-footer and data-accuracy-contract boilerplate is generic policy text that inflates the definition without being specific to this tool.

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

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

With no output schema, the description covers the key post-call state changes (registration persisted, brand appears in listings, primary defaulting) so an agent knows what invoking it accomplishes. It omits only failure modes and the shape of the success 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 100%, so baseline is 3, but the description adds semantics the schema does not carry: the defaulting behavior ('per-channel my_youtube_* tools default to this brand when no channel_id is supplied') and the auto-primary-on-first-registration rule.

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

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

States a specific verb+resource ('Register a YouTube Brand Account channel') and enumerates the concrete effects: resolving channel_id from the @handle, persisting the registration, and surfacing the brand in list_my_youtube_channels. It is clearly distinguishable from remove_my_youtube_brand_channel and set_my_primary_youtube_channel.

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

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

Gives an explicit prerequisite ('Use after get_youtube_channel(handle='@Brand') confirms the channel exists') and explains the set_as_primary defaulting rule. It does not explicitly say when to prefer this over set_my_primary_youtube_channel, which is the one remaining routing gap.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the bar is lower, and the description adds genuine behavioral traits: the 15-minute, any-replica provenance receipt and the verified vs unverified_model_data distinction for downstream rendering. It does not cover auth requirements, rate limits, or error behavior of the connector itself.

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?

Roughly two-thirds of the text concerns chart_render's calling convention, provenance tokens, attribution footers, and the accuracy contract rather than this tool's own invocation. The actual purpose is front-loaded, but the bulk is off-topic bloat that dilutes the signal for selecting and calling this connector.

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 seven-action connector with no output schema, the description explains the data domain and downstream contracts but does not say which action answers which question or what each returns beyond the truncated schema text. It is adequate but leaves selection among its own actions to inference.

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%, so the enum descriptions and per-action params object already document every field (domain, country, limit, keyword). The description adds no syntax, default, or format detail beyond the schema, 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 opening sentence names the platform and enumerates the concrete SEO resources it covers (domain rating, backlinks, organic keywords, referring domains, competitors, top pages, keyword research), which map one-to-one onto the action enum. An agent can tell it is the SEO data connector, though it never explicitly contrasts itself with the sibling semrush_connector or ahrefs_dashboard.

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 gives extensive procedural guidance about downstream steps (when to call chart_render, passing provenance_token, appending the attribution footer, the data-accuracy contract), but says nothing about when to choose this connector over semrush_connector or ahrefs_dashboard, nor which action to pick for a given question. Usage is implied through the token/downstream rules rather than explicit tool-selection criteria.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: results are non-authoritative estimates, coverage is explicit top-N, and there is an integrity/attribution contract governing how to present output. This goes well beyond the annotations, though it omits freshness/latency or rate-limit characteristics.

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

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

Purpose is front-loaded in the first sentence, which is good, but the remainder is a dense, repetitive block of 'do not' rules and attribution instructions that is longer than needed for the core call. It remains readable but parts could be tightened.

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

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

An output schema exists, so return values need not be re-described, and the behavioral/attribution contract is thorough. However, the absence of any parameter guidance leaves a real gap for a tool requiring a domain argument.

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

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

Schema description coverage is 0% for two parameters (domain, country), and the description says nothing about either. With no compensating explanation of the country pattern or the domain scope, an agent gets no added meaning beyond the bare 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 opening clause gives a specific verb (Fetch) and named resources (Ahrefs domain overview, top organic keywords, top pages) and the output form (estimate dashboard). It is clearly distinct from generic connectors, though it never explicitly contrasts itself with the sibling ahrefs_connector or semrush_dashboard.

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 choose this tool over ahrefs_connector or a featured_seo_audit, nor any prerequisites. The rules present concern output handling, not tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description then spends significant text on the chart_provenance / provenance_token handoff and attribution footer protocol, which is behaviorally relevant and not in the structured fields. However, it doesn't cover pagination behavior, rate limits, or whether the connector requires per-base authorization. Given annotations carry safety, this is adequate but not rich.

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 first sentence is good, but the rest is a long operational contract about chart_render, provenance tokens, attribution footers, and data-accuracy rules that dominates the definition. It is poorly front-loaded for a tool-selection decision and much of the content belongs in a system/policy prompt rather than a tool description.

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 multi-action connector with 100% schema coverage and no output schema, the schema provides the call semantics. The description supplies the surrounding data-handling contract but omits what the records actually look like and any pagination/output guidance. It is complete enough to invoke but not to use well.

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%: the enum documents each action and the params object documents per-action fields. The description adds no parameter-level detail beyond what's in the schema. Per the rubric, baseline is 3 when schema coverage is high.

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 opening sentence names the resource (Airtable bases, tables, records) and the operations (browse, search, retrieve structured data). This is clear and actionable. However, the tool's own schema reveals five distinct actions (list_bases, list_tables, list_records, search_records, get_record) plus optional filtering, sorting, and pagination; the description doesn't mention get_record or list_tables explicitly, so the multi-action nature is only fully visible after opening the schema.

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

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

It routes the agent to chart_render for visual/trend/comparison/recap requests, which is useful routing. But it never says when to use this tool versus sibling connectors like crm_connector, notion_connector, or drive_connector – i.e., what data belongs in Airtable. The when-not-to-use case is absent.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description is fully consistent with that read-only profile. It adds genuinely non-obvious behavior: a 15-minute provenance-token validity window usable across replicas, mapping of values to source_path, and the rule that unverified values are labeled unverified_model_data. It says nothing about rate limits, pagination limits, or permissions, so it stops short of 5.

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

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

Purpose is correctly front-loaded, but the body is a long block in which the majority of sentences describe chart_render and attribution behavior rather than this connector. The provenance and accuracy-contract content is relevant yet disproportionately verbose and reads like shared boilerplate.

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 9 actions, nested params, no output schema, and annotations already carrying the safety profile, what remains genuinely useful is the data-integrity and verification contract, which the description supplies. Gaps are minor: nothing tells the agent about the connector's own limits (pagination, throttling, auth scope) beyond what annotations state.

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 enum plus params object fully document all nine actions and their per-action arguments, so the baseline is 3. The description adds no parameter-level detail (formats, defaults, constraints) beyond what the schema already provides.

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 opening sentence names the resource and its content domains precisely ('Amazon Seller Central data: orders, inventory, sales metrics, and seller account performance'), so an agent knows this is the Amazon seller data connector. It does not state a verb or explicitly differentiate from siblings like ebay_connector or shopify_dashboard, but the domain 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 gives extensive guidance on how to consume results (when to call chart_render, when to pass provenance_token, attribution footer handling) but says nothing about when to select this connector over alternatives or what preconditions the seller account must satisfy. Tool-selection guidance is only implied by the data domain.

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 (readOnly/idempotent/openWorld), the description discloses fail-closed behavior for unsupported runbooks and missing prerequisites, the read-only tool allowlist, and that a verifiable execution receipt plus warnings and source evidence are returned. These are meaningful operational traits an agent cannot get from annotations alone.

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

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

Purpose and mode semantics are front-loaded before the alternative-tool guidance and the contracts, so the structure is sound. The trailing attribution-footer and data-accuracy contracts are lengthy, though they are genuine safety instructions rather than filler.

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

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

With no output schema, the description compensates by enumerating return content (answer, source evidence, warnings, execution receipt) and failure behavior. Given six parameters and nested arguments, the definition supplies everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by explaining the routing logic behind mode (router_first vs required_runbook) and the pinning of explicit runbook ids that the terse schema properties only summarize. It does not add format/syntax detail for version, content_hash, or arguments beyond what the schema already provides.

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

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

States a specific verb+resource: 'Answer a business question through CorpusIQ's deterministic server-side runbook executor.' It clearly frames itself as a high-level orchestration entry point and contrasts with raw connector tools. It does not, however, explicitly distinguish itself from closely related siblings like run_runbook, select_runbook, or list_runbooks, which the agent may confuse with this router.

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

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

Gives explicit when-to-use ('supported executive financial-health or financial snapshot workflows even when the user names QuickBooks') and when-not ('Use raw connector tools for simple lookups that are not executive workflows'). The two modes and their selection conditions are also spelled out, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds genuinely useful non-annotation behavior: read-only access via a personal userApiKey, the provenance_token handoff to chart_render with its 15-minute window and cross-replica validity, the unverified_model_data fallback, the mandatory attribution footer, and a data-accuracy contract. It stops short of pagination/rate-limit behavior, which the schema hints at but the prose never explains.

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 purpose and join keys are correctly front-loaded, but roughly half the text is cross-cutting platform policy (chart_render routing, provenance mechanics, footer formatting, accuracy contract) that does not help an agent select or invoke this connector. Those sentences are long and repetitive, diluting the tool-specific content.

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 multi-action connector whose safety profile is fully covered by annotations and whose action semantics are documented in the schema, the description covers the important gaps: auth model, cross-source join keys, and output-handling rules. Only pagination/return-shape behavior and sibling differentiation are absent, which are minor given the absence of an output schema and the read-only nature.

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%: the action enum carries per-action 'use when the user asks...' text and the params object documents each action's argument shape. The description adds no parameter-level detail of its own (the join keys it lists are output fields, not inputs), so the 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 opening sentence names a specific resource family (CRM + invoicing + accounting) and enumerates the concrete entities exposed (companies, quotations, invoices, opportunities, expenses, payments, suppliers, products, contracts, employees, custom fields), so an agent knows exactly what domain this connector serves. It does not, however, distinguish itself from the sibling axonaut_dashboard, so an agent must infer which Axonaut surface to pick.

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

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

The description supplies real usage context — the cross-connector join keys (email, siret, company_name, invoice_id, currency) that make this data useful for Stripe/QuickBooks/HubSpot reconciliation — which is more than generic filler. But it gives no explicit when-to-use/when-not versus axonaut_dashboard, and no guidance on choosing among the 19 actions beyond what the schema already carries.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the bar is lower, yet the description still adds real behavioral context: calculations are date-bounded and currency-safe, an integrity receipt is produced, and the agent is told to preserve the attribution footer verbatim. The data-accuracy contract is mostly generic policy, but the attribution and integrity-receipt disclosures are genuine additions.

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 purpose and inputs are front-loaded well, but a large share of the text is a generic 'Data accuracy contract' about inventing budgets, ROAS, CPA, and editorial labels that is largely server-side policy rather than tool-specific guidance. Several sentences do not earn their place in a per-tool definition.

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

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

With an output schema present, the return payload need not be explained, yet the description still previews what the caller receives and covers defaults, date bounds, and the attribution obligation. The only real gap is the absence of sibling routing, which is minor given the distinct dashboard 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 description coverage is 100%, so the baseline is 3, and the description earns above baseline by supplying the default values (30daysAgo/today) and the 366-day maximum range constraint, which is not encoded anywhere in the schema. It does not add syntax beyond what the pattern field already shows.

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

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

The first sentence names a specific verb (fetch) and enumerates the exact resources (Axonaut invoices, payments, opportunities, account data) and the artifact returned (evidence-backed CorpusIQ PNG dashboard plus text, facts, reconciliation status, integrity receipt). This is clearly distinct from the raw axonaut_connector sibling, which would not produce a rendered dashboard artifact.

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

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

The description states the date defaults (30daysAgo/today) and the 366-day ceiling, which is useful operating context, but it never says when to choose this over axonaut_connector, dashboard_render, or chart_render. There are no explicit exclusions or alternative routing, so usage must be inferred from the tool name and output type.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the core safety profile. The description adds the OAuth 2.0 auth requirement and the need for a verified site, which is useful. It does not disclose rate limits, error behavior, or output format details beyond annotations, hence a 3.

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 long and includes extensive instructions about chart_render, provenance tokens, attribution footers, and a data accuracy contract that are not specific to invoking this tool. These dilute the core purpose and make it less 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 the fully covered schema and annotations, the description provides an adequate overview of the data returned and auth context. It could be more focused on the tool itself, but the necessary information for calling the tool is present.

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

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

Schema description coverage is 100% and the action enum and params object are fully documented in the schema. The description adds no parameter-specific semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

States the resource (Bing Webmaster Tools organic-search data) and enumerates the data domains it returns. It is specific but does not explicitly contrast with sibling connectors like search_console_connector or ahrefs_connector.

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?

Lists clear use cases (Bing SEO reporting, organic-search visibility, keyword analysis, crawl health, backlink volume). However, it offers no exclusions or guidance on when to choose this connector over alternatives like bing_webmaster_dashboard or search_console_connector.

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

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

Annotations already declare the safe read-only/idempotent profile, so the bar is lower. The description still adds real behavioral context beyond them: the tool returns an authoritative PNG with daily reconciliation and 'integrity receipts', and the data-accuracy contract defines what the agent may and may not assert. It does not mention rate limits, auth scope, or 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 purpose is front-loaded in the first sentence, which is good. But the remainder is long contractual boilerplate with repetition ('do not invent or infer' restated as 'do not turn it into plain text, invent a URL, or omit it') that dilutes the operational content.

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

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

An output schema exists, so return-format explanation is not required, and the description covers the accuracy contract and attribution-footer handling an agent needs after the call. It is close to complete; the main gap is not relating itself to the connector sibling.

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%; start_date and end_date already carry format descriptions, and site_url has none. The only added parameter meaning is 'exact verified site', which implies site_url must match a verified property but does not explain acceptable formats or what happens on unverified input. 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?

It states a specific verb and resource: fetch Bing-reported impressions, clicks, and top queries for an exact verified site and return a PNG dashboard. That is concrete and agent-actionable. However, it never references the sibling bing_webmaster_connector, so the boundary between the raw connector and this dashboard tool must be inferred.

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

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

Usage is implied by the target resource (a verified site) and the output type (a rendered dashboard), but there is no explicit when-to-use statement and no exclusion or alternative such as the connector sibling. It also gives post-call output handling rules, which is guidance about responding rather than about when to select 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered externally. The description adds a verification/provenance contract (verified vs unverified_model_data, receipt validity window) that goes beyond the annotations, but it never states anything concrete about this tool's own behavior such as pagination, empty results, or auth failures.

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 purpose is correctly front-loaded in one sentence, but the rest is largely generic boilerplate about chart_render, attribution footers, and a data-accuracy contract that applies to a read-only calendar connector only tangentially. It is several times longer than needed to convey the tool's actual behavior.

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, so the description could helpfully say what the connector returns (event lists, calendar metadata, folder counts), and it does not. The action/enum schema plus the readOnly annotations cover most of what an agent needs to invoke correctly, so this is adequate but with a visible gap on return-shape expectations.

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

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

Schema description coverage is 100%: the action enum and the params string document each action's required fields, auth requirements, and optional arguments in detail. The description adds no parameter-level meaning beyond echoing some action names, so the 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 opening sentence names specific verbs and resources (list upcoming meetings, search events) across Google Calendar and Outlook, which cleanly separates it from non-calendar siblings in the list. However, 'check availability' corresponds to no action in the enum (which only offers list/search/get), so the purpose partly over-promises compared to what the tool actually exposes.

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 gives no guidance on when to use this connector versus alternatives such as calendly_connector, nor which of the nine actions to pick for a given user request. The only routing advice provided concerns chart_render, a downstream sibling, which is not usage guidance for 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 already establish readOnly/idempotent/non-destructive safety, so the bar is lower, and the description clears it by disclosing non-obvious behavior: a 15-minute provenance window valid on any replica, the unverified_model_data fallback when no receipt exists, and a verbatim attribution-footer obligation. It stops short of auth, pagination, or rate-limit behavior, but this is genuinely additive context beyond the structured fields.

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

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

The purpose is front-loaded, but the bulk of the text is reusable orchestration boilerplate, and the data-accuracy contract references 'campaign budgets, frequency, ROAS, CPA' — advertising concepts with no bearing on Calendly scheduling data, which reads as template noise. Multiple sentences do not earn their place in a tool-specific definition.

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

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

For a seven-action connector with full schema coverage and no output schema, the description covers the data domain and the downstream chart/provenance contract adequately. It omits authentication requirements, pagination semantics, and per-action scope, leaving the agent to rely entirely on the enum descriptions for action-level detail.

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% — the action enum and params object fully document every accepted argument — so the baseline is 3. The prose adds nothing about parameter syntax or formats, which is acceptable given the schema does the work, but it also fails to compensate for anything, so no credit above baseline.

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

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

The opening sentence names a specific resource and four data categories ('scheduled events, event types, invitee lists, and user availability'), so the agent knows roughly what the connector exposes. However, it never enumerates the seven actions the tool actually performs and never distinguishes itself from the sibling calendar_connector, so the purpose stays at a vague level.

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?

Guidance is entirely about downstream orchestration (call chart_render for visuals, pass provenance_token within 15 minutes) rather than when to choose this connector over calendar_connector or any other sibling. The agent can infer that Calendly questions should route here, but there is no explicit when/when-not statement for the tool itself.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world. The description reinforces read-only and adds substantial context: default-deny on writes, a provenance token flow (15-minute window, any replica, source_path mapping), chart_render labeling semantics, attribution footer handling, and a data accuracy contract. This goes well 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 lengthy and front-loaded correctly, but it haws into multiple tangential domains (provenance tokens, chart_render routing, footer verbatim requirements, data accuracy contract). Many of these are operational policies that dilute the core tool purpose and would be better placed in separate documentation or a shared policy tool.

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

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

For a read-only connector with no output schema, the description is quite complete: it enumerates resource types, return fields, safety posture, and integration with chart_render. The provenance and footer instructions are detailed, though they may be overkill for a connector tool. The completeness is strong, but the description lacks explicit error-handling or pagination behavior for calls.

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 enum descriptions are detailed (each action includes required params and return summary). The description lists the same resources but adds no new parameter-level detail beyond what the schema and nested enum descriptions already provide. Baseline 3 is appropriate.

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

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

States a specific verb+resource (read access to CallRail call-tracking), names the exact data returned (accounts, companies, tracking numbers, calls with source/duration/caller), and distinguishes from first-party connectors by noting it's a breadth-tier connector via Nango.

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 routes use cases (call-attribution, phone-lead, which-campaign-drove-calls questions) and explicitly states writes are not exposed (default-deny). Also directs to chart_render for visuals. However, it does not contrast with sibling connectors like google_ads_connector or clarify when to use this vs. another CRM connector.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description usefully adds that only user-saved content is returned and imposes an attribution-footer and data-accuracy contract. The attribution/accuracy text is largely output-format guidance rather than tool behavior, and nothing is said about volume, pagination, or what 'recent decisions' actually yields.

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

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

Purpose and the key routing decision are front-loaded in the first two sentences. It runs long, with the accuracy contract and footer instructions consuming several sentences, but each carries distinct operational guidance rather than restating the schema.

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

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

With no output schema, the description does step in to characterize the return (declared facts, decisions, metric specs) and constrains how to treat returned fields. It stops short of describing what a response looks like or how the token budget shapes it, leaving a modest 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?

One parameter with 100% schema description coverage, so the schema already documents token_budget and its default. The description adds nothing about token budget behavior or truncation, so it earns only the baseline for high coverage.

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

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

States a concrete verb and three specific resources (canonical facts, recent decisions, declared metric specs) plus the 'user-declared/user-approved' scope. This cleanly separates it from siblings like canonical_facts_list, canonical_decisions_list, and metric_spec_list, which each cover a single slice.

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 enumerates when to call it (start of business, product, pricing, company, positioning, board, investor, factual, KPI questions when stable truth matters) and names the alternative routing decision: prefer metric_spec_resolve over recomputing KPIs from raw connector calls.

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 give the generic safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds genuinely non-obvious behavior: the call is a staged preparation rather than a persistence, it returns a pending_write_id, and committing requires an explicit user confirmation through a sibling tool. That is the kind of operational context annotations cannot express.

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

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

The operationally critical facts (no immediate save, pending_write_id, explicit confirmation) are correctly front-loaded, but roughly half the text is a generic data-accuracy/attribution policy block that is not specific to this tool and would read identically on many other definitions. That boilerplate dilutes an otherwise tight, well-ordered description.

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 there is no output schema, the description covers the return value (pending_write_id) and the full lifecycle needed to call the tool correctly, including the follow-up commit step and its confirmation requirement. Nothing an agent needs to avoid a mistaken silent write is missing.

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

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

Schema description coverage is 100% and both parameters ('text', 'context') are already documented in the schema, so the baseline is 3. The description adds no format, length, or content guidance for the decision text or context beyond what the schema states.

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

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

States a specific verb and resource ('Prepare a write to the canonical decisions log') and immediately qualifies the scope with 'this tool does not save immediately', which distinguishes it from canonical_decisions_list and canonical_pending_commit. An agent can identify its role in the two-phase write flow without opening any schema.

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

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

Explicitly names the trigger conditions ('when the user wants to log a decision or when you ask Log to canonical decisions?') and the exclusion ('Never silently log decisions'). It also names the alternative and the condition for invoking it ('Commit only after the user explicitly says yes by calling canonical_pending_commit'), which is exactly the when/when-not/alternative guidance the rubric rewards.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and "Read-only" merely restates that. The description earns credit for disclosing two traits the annotations don't: a mandatory attribution-footer passthrough on output and a data-accuracy contract restricting derived metrics and labels. Pagination/return shape is still unspecified.

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

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

Purpose is correctly front-loaded in the first sentence. However, the bulk of the text is a generic data-accuracy policy that would apply to virtually any data tool, making the description noticeably heavy for a one-parameter read-only list. Some sentences do not earn their place for this specific tool.

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

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

Low tool complexity and no output schema mean the description needn't explain return values, and it does handle output consumption rules well. Still missing are what a "decision" record contains and how `limit` affects results, leaving an agent with gaps for even this 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?

Schema description coverage is 0% for the single `limit` parameter, which appears as a bare integer with default 50. The description never mentions limit, page size, or result caps, so an agent gets no meaning beyond the field name. Only the word "recent" loosely gestures at result scope.

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

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

States a specific verb and resource: "List recent canonical decisions for this user." That clearly separates it from canonical_decisions_add and from the canonical_facts_list/context siblings. It doesn't explicitly name an alternative, so it stops short of 5.

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

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

There is no guidance about when to reach for this tool versus canonical_facts_list, canonical_context_get, or canonical_decisions_add. The word "recent" hints at a recency window but no selection criteria, prerequisites, or exclusions are given. Usage is only implied by the tool name.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value beyond them: the attribution-footer handling rule and the data-accuracy contract governing what may be treated as verified. It does not say what happens when a key is absent or unrecognized, which is the main behavioral gap.

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

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

Purpose and usage are correctly front-loaded, but the bulk of the text is a long, largely generic accuracy/attribution boilerplate that is not specific to this tool. It reads as policy text pasted onto a one-parameter lookup, diluting an otherwise terse definition.

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

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

Covers read-only nature, intended use, and output-handling rules, but there is no output schema and no statement of the returned fact's shape or the missing-key behavior. Adequate for a simple lookup, with recognizable gaps.

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

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

Schema description coverage is 100% for the single 'key' parameter, so the schema already documents it. "By key" only restates the lookup semantics; no key format, namespace, or example keys are added.

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

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

States a specific verb and resource ("Get one declared canonical business fact by key") and the singular-by-key framing implicitly separates it from canonical_facts_list and canonical_facts_set. It never names those siblings explicitly, so an agent must infer the boundary from the wording alone.

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

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

"Use when the user asks for a stored fact such as pricing, connector count, tagline, team detail, certification, or product fact" gives concrete triggering contexts. No exclusion or alternative routing (e.g. when to use canonical_facts_list instead) is stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so safety is covered. The description goes further with the attribution-footer obligation and a data-accuracy contract about not inventing fields or presenting derived metrics as source data, which is real behavioral context beyond the annotations.

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

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

The core purpose is front-loaded in the first sentence, which is good. But the body is long and much of it is conditional boilerplate (footer handling, a lengthy accuracy contract) that reads as generic guardrail text rather than essential tool-selection information.

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

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

With no output schema, the description must convey enough about returns, and it does gesture at the output shape via the attribution footer and the 'only returned fields are verified' contract. It does not describe the fact record structure or result ordering, but for a simple read-only list behind rich annotations this is largely sufficient.

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% for the single optional 'category' parameter, so the schema already carries the semantics. The description only restates 'optionally filtered by category' and adds no example categories or format details 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?

States a specific verb and resource ('List declared canonical business facts') plus an optional filter, so the agent knows exactly what it retrieves. It does not, however, distinguish itself from the adjacent canonical_facts_get sibling, which shares the 'canonical facts' domain.

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 the category filter is optional and marks the tool read-only, implying use for browsing the full set rather than retrieving one fact. There is no explicit statement of when to prefer this over canonical_facts_get or truth_sources_list, so the guidance remains implied.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false, so the safety profile is already structured. The description adds genuinely non-structured behavior: a two-phase deferred write that returns a pending_write_id, a mandatory human confirmation gate in the same conversation, and output-contract rules (attribution footer must be reproduced verbatim; only returned fields count as verified). These are real obligations an agent could not derive from the schema or annotations.

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

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

Purpose and the critical never-saves-immediately constraint are front-loaded correctly, which is the right structure for a write gate. However, a large fraction of the text is generic data-accuracy and attribution boilerplate (no invented budgets, ROAS, CPA, 'waste' labels) that reads like a global policy rather than tool-specific guidance, diluting the definition.

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

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

With no output schema, the description does the necessary work of stating what the call returns (a pending_write_id) and the exact downstream step needed to persist the fact, plus the confirmation precondition. The remaining gap is the absence of any field-level semantics for the three required inputs.

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

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

All three parameters (key, value, category) are required and schema description coverage is 0%, so the description carries the full burden — and it never explains what key/value/category should contain, what formats are valid, or how category is constrained (it has a default of 'general' but no guidance). It refers only to 'the exact fact', which does not map to the three 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?

States a specific verb (Prepare a write) plus resource (a declared canonical fact) and immediately distinguishes itself from siblings by declaring it does not save immediately and by naming canonical_pending_commit as the follow-up. An agent can tell it apart from canonical_facts_get/list, canonical_pending_commit, and canonical_pending_cancel without opening any schema.

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

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

Explicit lifecycle instruction: call only after proposing the exact fact to the user, then call canonical_pending_commit with the pending_write_id once the user explicitly answers yes in the same conversation. It also states an exclusion ('Never silently save inferred or guessed facts') and names the alternative tool, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=true, and openWorldHint=false. The description adds no additional behavioral detail about what exactly is destroyed, whether cancellation is reversible, or what permissions are needed; the remaining text is generic response and data-accuracy boilerplate.

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 first sentence is useful and front-loaded, but the following sentences are largely generic attribution-footer and data-accuracy instructions that are not specific to this cancel operation. They inflate the description without helping an agent invoke this tool correctly.

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 one-parameter destructive cancel, the purpose and trigger condition are covered, and annotations supply the safety profile. However, the missing parameter guidance and lack of tool-specific behavioral details leave a clear gap, while the generic data-accuracy contract is not relevant to this operation.

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

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

Schema description coverage is 0% and the description does not mention pending_write_id at all. It neither explains where to obtain the ID nor its expected format, so the description fails to compensate for the undocumented 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 first sentence states a specific verb and resource: 'Cancel a pending canonical write.' This clearly distinguishes the tool from siblings such as canonical_pending_commit, though it does not explicitly name the alternative commit 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?

It states a clear usage condition: use when the user says no or changes their mind. This gives direct context for invoking the tool, but it does not explicitly name canonical_pending_commit as the alternative action or describe 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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the hard gate that a pending write must be user-confirmed before committing, plus where the pending_write_id comes from. It stops short of stating what the commit does to the pending record or whether it is reversible/repeatable.

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, precondition, and ID provenance are front-loaded and earn their place, but the trailing attribution-footer and data-accuracy-contract paragraphs are generic boilerplate that applies to any tool in this family rather than this one. They pad the definition and dilute the key gating instruction.

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 2-param, non-idempotent, destructive commit with no output schema, the definition covers purpose, precondition, and parameter sourcing. It does not describe the post-commit effect (e.g., whether the pending entry is consumed or what the tool returns on success), which is the main remaining gap.

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

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

Schema coverage is 50% (only user_confirmation is documented in-schema), so the description has to compensate. It does so usefully: it says pending_write_id must come from canonical_facts_set or canonical_decisions_add, and that confirmation must follow an explicit yes, which matches the accepted values described for user_confirmation.

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

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

States a specific verb and resource ('Commit a pending canonical fact or decision write') and clearly distinguishes itself from siblings by naming the tools that produce the pending_write_id (canonical_facts_set, canonical_decisions_add) and implicitly excluding the cancel path. An agent can tell exactly what this does without opening the schema.

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

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

Explicit when/when-not: only call after the user explicitly confirmed yes, and 'Do not call unless the user has just confirmed the exact pending write.' It also points to where the required ID originates. Routing and preconditions are fully covered.

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/idempotent/non-destructive, and the description adds substantial context beyond them: the provenance-token trust model, safe downgrade to 'unverified' on missing/expired/wrong-user/mismatched receipts, the 15-minute receipt lifetime, cross-replica scope, and the attribution-footer requirement. This is exactly the kind of behavioral detail that cannot be inferred from 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?

Purpose and usage are front-loaded in the first two sentences, and the routing rule is placed early. The trailing data-accuracy contract and attribution-footer instructions are lengthy and partly generic policy boilerplate, but they are relevant to using this tool's output correctly, so the length is mostly earned.

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

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

An output schema exists, so return values needn't be described, and annotations cover the safety profile. The description nonetheless covers provenance trust, downgrade behavior, receipt lifetime, cross-replica validity, sibling routing, and output-handling obligations—nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is only 29%, so the description must compensate, and it does for the critical params: it explains how provenance_token interacts with source_path/secondary_source_path and that source is a display label only. However width, height, and template receive no description-level explanation, leaving a gap that the schema doesn't fully fill.

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

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

States a specific verb+resource+output ('Render numeric data as a deterministic CorpusIQ PNG plus a complete text summary') and names the sibling it is not ('For verified live GA4 data use dashboard_render instead'). An agent can distinguish it from dashboard_render without opening either schema.

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

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

Gives an explicit when-to-use trigger ('visualize, chart, compare, or recap values already present in the conversation') plus an explicit alternative and the condition selecting it (verified live GA4 data -> dashboard_render). Both the invoke condition and the exclusion are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: OAuth 2.0 auth, the 15-minute cross-replica provenance_token window, and the attribution-footer/accuracy contract. However, much of this text governs the downstream chart_render tool rather than this connector's own 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 first sentence is a well front-loaded domain summary, but the bulk of the description is boilerplate about chart_render, provenance tokens, footers, and the data-accuracy contract. That material is verbose and largely tangential to invoking this connector, diluting the signal.

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 enum descriptions do the heavy lifting on return fields, and the description covers auth and usage context. It is nearly complete for a read-only connector, though it omits pagination behavior and any explicit note on result limits.

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%, with the action enum and per-action param shapes fully documented inline. The description restates the resource categories but adds no syntax, format, or defaulting detail beyond what the schema already 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 names a specific platform (Close CRM) and enumerates the resources it exposes: leads, opportunities, activities, full-text search, and organization users. That is enough for an agent to grasp the domain, but it never states a verb for the tool itself (the actions live only in the enum) and does not distinguish it from the many sibling CRM connectors such as crm_connector or salesforce_connector.

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 explicit use cases: 'sales pipeline reporting, lead/contact lookup, rep-level activity attribution, and sales-funnel analytics,' which is clear contextual guidance. It offers no exclusions or comparison against alternative connectors, so it stops short of the top tier.

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

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

Annotations already declare the read-only, idempotent, non-destructive, closed-world profile, so the bar is lower. The description still adds genuine context beyond them: the tool does not connect directly but returns a browser URL to a credential setup form, and it specifies attribution-footer handling for the response.

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 purpose and trigger phrases are correctly front-loaded in the first three sentences, but the majority of the text is generic boilerplate. The data-accuracy contract enumerating 'campaign budgets, frequency, ROAS, CPA, revenue' is clearly irrelevant template text for a GunBroker connect tool, and it dilutes the useful content.

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 connect tool with no output schema, the description covers what the tool does, when to invoke it, and what it returns. It omits edge cases such as reconnecting when already connected or URL expiry, but the essential information is present.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-related detail is missing.

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 opening states a specific verb and resource ('Connect your GunBroker seller account') and immediately adds the return behavior ('Returns a browser URL to open the credential setup form'). This clearly distinguishes it from siblings like disconnect_gunbroker_connection and get_gunbroker_connection_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?

Explicit trigger phrases are given ('connect GunBroker, set up GunBroker, or link my GunBroker account'), which is strong positive guidance. However, there is no when-not guidance or mention of the alternative sibling (e.g., checking status first via get_gunbroker_connection_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 already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower, and the description still adds real behavioral context: a 15-minute provenance-token validity window, any-replica acceptance, the fallback label unverified_model_data, mandatory verbatim attribution footers, and a data-accuracy contract forbidding invented metrics. These are output-handling constraints the annotations do not convey.

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

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

The description is front-loaded correctly with the connector's domain, but only one of roughly eight sentences concerns this tool; the remainder is generic chart_render/attribution/accuracy boilerplate that likely repeats across every connector. The material is individually useful but disproportionately weighted away from the tool being described.

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 21-action read-only connector with 100% schema coverage and no output schema, the description covers the domain and the downstream handling obligations well, and the action enum supplies per-action purpose and 'use when' cues. The remaining gap is sibling disambiguation against the other email-marketing connectors, which nothing in the definition resolves.

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 (action and params) are fully documented in the schema, including per-action parameter shapes, so the baseline of 3 applies. The description adds no parameter-level meaning of its own, not even a note on how the params object is keyed to the action value.

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 opening clause names the domain and the four resource families (contacts, email campaigns, lists, engagement metrics), which is a legitimate scope statement for a 21-action connector. However, it offers no verb and no differentiation from the near-identical siblings mailchimp_connector, klaviyo_connector, and activecampaign_connector, so an agent cannot tell from the description alone why it should pick Constant Contact over those.

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 gives detailed routing rules, but they govern chart_render and attribution handling rather than this connector; the only implicit usage signal is that this tool returns numeric values suitable for charting. There is no statement of when to use this connector versus the other email-marketing connectors, so the agent must fall back on the per-action 'Use when...' text embedded in the action enum.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description goes beyond that by disclosing the 15-minute provenance-token window, replica-agnostic reuse, the unverified_model_data fallback, and a data accuracy contract — genuinely useful operational context that is consistent with the read-only 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?

Purpose is front-loaded in the first sentence, but the bulk of the text is cross-cutting governance for chart_render, provenance tokens, attribution footers, and data contracts rather than this connector's own behavior. Much of it likely duplicates instructions carried by chart_render, making it verbose for what it adds here.

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 20-action connector with no output schema, the enum descriptions carry the action-level detail and the description carries the behavioral contract. It is fairly complete, though it never characterizes the shape or format of returned records, which is the main remaining gap.

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

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

Schema description coverage is 100%: the action enum and the params object document every action and its arguments in detail. The description adds no parameter-level syntax or constraints beyond that, so the baseline 3 for schema-driven documentation 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 first sentence names a specific domain (CRM across HubSpot and LeadConnector) and enumerates the resources covered: contacts, deals, pipelines, companies, opportunities. This distinguishes it from sibling CRM connectors like salesforce_connector or close_connector. The multi-action verb itself is vague, but the enum supplies the specific operations.

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 gives rich guidance on downstream behavior (when to call chart_render, provenance token reuse) but never states when to select this connector over alternatives such as salesforce_connector or podium_connector. Usage is implied by the named CRMs rather than explicitly routed.

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

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

Annotations only cover safety/idempotency; the description adds substantial context they cannot: a 15-minute provenance-token validity window valid 'on any replica', the unverified_model_data fallback labeling, the mandatory attribution footer requirement, and a data-accuracy contract governing derived metrics. This is exactly the behavioral disclosure structured fields cannot carry.

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

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

Front-loaded with purpose, then downstream routing, then the accuracy contract — a logical progression with no throwaway sentences. It is dense and somewhat long, but each sentence carries a distinct obligation (provenance, footer, data honesty) rather than restating structured data.

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?

Despite having no output schema, the description tells the agent what the tool returns (correlation values plus a possible provenance token and attribution footer) and how to consume them. For a nested-parameter, openWorld read connector, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% — the action enum and the nested params object are fully documented in the schema, including the per-action {customer_id, property_id, start_date, end_date} shape. The description adds only a loose paraphrase of the same correlations, so baseline 3 is appropriate.

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

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

States a specific verb+resource pair — 'Cross-source analysis correlating Google Ads spend with GA4 web traffic and revenue' — and names the exact platforms being joined. An agent can immediately distinguish this from the single-source google_ads_connector and ga4_connector siblings.

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

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

Explicit trigger: 'Use when comparing ad spend to sessions, conversions, or ROAS across platforms', plus routing rules to chart_render for visuals. It gives strong positive guidance but never states when NOT to use it (e.g., single-source queries belong to google_ads_connector), so it falls short of explicit alternative routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description still adds substantial behavioral context beyond them: the 15-minute provenance_token validity window, that it may be passed on any replica, that values must be mapped to exact source_path, the consequence of an invalid receipt (unverified_model_data labeling), and a data-accuracy contract forbidding invented metrics. This is unusually rich disclosure for a read-only connector.

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 purpose is front-loaded, but a large share of the text is downstream rendering/provenance policy that belongs to chart_render rather than this connector, which inflates the definition. The accuracy contract is valuable, yet the block is long and mixes tool selection guidance with response-formatting rules.

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, multi-action connector with no output schema, the description covers the analytical purposes, the action set (via schema), provenance rules, and the data-accuracy contract. It is silent on the shape of returned values or data-availability caveats, but there is no output schema obliging it to explain returns, so the coverage is close to complete.

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

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

Schema description coverage is 100% and the action enum and per-action params object are fully itemized in the schema, so the description's job here is minimal. It adds no date-format, pagination, or external_shopify_data syntax detail, 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 names a specific verb and resource ('Cross-source analysis correlating Klaviyo email activity with web traffic, ecommerce revenue, and ad spend') and enumerates the analytic purposes (channel attribution, email-driven revenue, unified marketing analytics). It is clear what the tool does, but it never distinguishes itself from siblings like cross_source_ads_connector or klaviyo_connector, leaving the agent to infer the boundary.

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

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

It states the contexts for use ('Use for channel attribution, email-driven revenue, and unified marketing analytics') and gives a downstream trigger (call chart_render when the user asks for a visual, trend, comparison, or recap). It does not say when NOT to use it or which sibling to prefer instead, so it stops short of full routing guidance.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantial behavior: the undimensioned query is the canonical KPI, eventCount requires exact agreement, sessions have matched/tolerance/bounded-variance/unverified states, and an integrity receipt is produced. That is real disclosure beyond the annotations, though it is framed largely as output semantics rather than invocation behavior (auth, rate limits).

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

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

Purpose and output list are front-loaded, and most sentences map to a real contract (reconciliation states, attribution footer, accuracy rules). However the body is a dense run-on block mixing output semantics, response-formatting instructions, and editorial guardrails, which makes it hard to scan and pushes well past the length a tool description needs.

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

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

Given an output schema exists, the description needn't explain return values, yet it usefully clarifies the reconciliation/verification semantics of those values and covers all five inputs plus the attribution-footer obligation. It is nearly complete; the missing piece is guidance on when to prefer this over sibling dashboards/connectors.

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 80% and the description's 'Inputs:' sentence essentially restates the schema (property_id required, start/end defaults, metric enum, event_name for eventCount). It adds no format or syntax detail the schema lacks, so the baseline 3 for high coverage 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 a specific verb (fetch) and resource (live Google Analytics 4 data) and enumerates the concrete outputs: PNG recap, accessible text, structured values, reconciliation status, integrity receipt. It is clearly distinguishable from connector siblings by its rendering role, but it never names an alternative (e.g. ga4_connector, chart_render) to sharpen the distinction.

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

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

Usage is only implied: the agent can infer you call this when you want a visual, verified recap of GA4 KPIs. There is no explicit when-to-use, when-not-to-use, or pointer to ga4_connector/chart_render as alternatives, so routing between this and its many siblings is left to inference.

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

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

Annotations show this is a non-destructive, idempotent operation. The description adds value by explaining the effect (tools hidden from active list, connector persists, appears as Paused in get_connector_status). One minor gap: doesn't mention if there are side effects on user sessions or whether disabling takes effect immediately for all agents.

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

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

Three dense sentences, each adding distinct value: first states the primary action, second gives usage cues and examples, third clarifies state persistence. Zero filler, perfectly 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?

For a simple one-parameter tool with annotations, the description covers purpose, when to use, state persistence, and relation to sibling tools. No output schema is needed since the tool is typically a fire-and-forget toggle. The tool is simple and the description is thorough.

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 100% coverage with a single required parameter connector_id and provides explicit examples. The description doesn't add parameter-level details beyond the schema, but with full schema coverage the baseline is 3. The description earns a 4 by linking the parameter to the usage examples ('disable Shopify' implies connector_id='shopify'), which adds practical context.

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 hides a connector's tools from the active tool list for the current user. It explicitly distinguishes from the sibling enable_connector by mentioning the reverse operation, and from get_connector_status by noting disabled connectors still appear there as 'Paused'.

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 to use when the user says they don't use a service or wants to pause a connector, and gives concrete examples like 'disable Shopify' or 'hide TikTok'. It also states the connector remains configured and can be restored with enable_connector, providing clear when-not-to-use context.

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, readOnlyHint=false, and idempotentHint=true. The description adds useful specifics that stored credentials are removed and the account is disconnected, but it does not cover auth requirements, reversibility, or side effects beyond what annotations 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 core purpose and trigger phrases are front-loaded, but the majority of the description is generic boilerplate about attribution footers and a data accuracy contract mentioning campaign budgets, ROAS, CPA, and revenue, which is irrelevant to disconnecting GunBroker.

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, destructive disconnect tool with rich annotations and no output schema, the description covers the action and when to use it. It could mention reconnection requirements or sibling alternatives, but it is largely 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 tool has zero parameters, so there are no parameter semantics to explain. The description does not need to compensate for schema gaps, making the baseline score of 4 appropriate.

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

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

States a specific verb and resource: 'Remove stored GunBroker credentials and disconnect the account.' It is clearly distinguishable from siblings like connect_gunbroker, get_gunbroker_connection_status, and reset_connector_token.

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

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

Gives explicit trigger phrases: 'disconnect GunBroker, remove GunBroker, or reset GunBroker.' However, it does not state when not to use it or name alternative tools such as disable_connector or reset_connector_token.

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

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: a 15-minute, cross-replica provenance_token receipt that lets chart_render preserve verified provenance, and the consequence of lacking one (values labeled unverified_model_data). It does not cover return format or pagination, but the added verification semantics are substantive.

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 purpose and routing guidance are front-loaded and efficient, but the tail is padded with cross-cutting policy — the attribution-footer rendering rules and the generic 'Data accuracy contract' boilerplate about campaign budgets, ROAS, CPA, and 'waste' — that is not specific to a file-storage connector and dilutes the tool-specific signal.

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 17-action multiplexed connector, the description establishes scope, cross-service routing, and the chart_render verification handoff, while the schema carries per-action semantics. It is close to complete; only return-format/pagination expectations are absent, and those are less critical for a read-only listing tool.

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

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

Schema description coverage is 100% — the action enum documents all 17 actions and the params field documents each action's argument shape. The description adds no parameter meaning beyond that, 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?

States specific verbs and resources: 'list, search, and read user-uploaded documents, spreadsheets, PDFs' across Google Drive, OneDrive, and Dropbox. It explicitly separates itself from sibling service connectors (Shopify, GunBroker, QuickBooks), so an agent can route correctly without opening the schema.

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

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

Gives an explicit positive trigger ('ONLY use this when the user explicitly asks about FILES, DOCUMENTS, or DRIVE contents') with examples, plus an explicit negative case and named alternative ('call the corresponding service connector directly instead'). Nothing is left to inference.

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

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

Annotations already declare this as a safe, idempotent, open-world read, so the bar is lower; the description still adds real behavioural context beyond them: the chart_provenance token's 15-minute validity window, its cross-replica portability, the fallback labelling as unverified_model_data when no receipt exists, and the mandatory attribution footer. It does not cover pagination, rate limits, or error behaviour of the connector itself, so it falls short of a 5.

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

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

The front-loaded data-domain sentence is efficient, but the remainder is dominated by a long provenance/attribution policy block aimed primarily at chart_render, plus a restated data-accuracy contract. Much of this is genuine policy, yet it is verbose, somewhat repetitive ('verified provenance' / 'unverified_model_data' restated), and pushes the tool's own behaviour into the background.

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

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

With no output schema and nested action-specific params, the description compensates well by defining the downstream contract (provenance token lifetime, source_path mapping, attribution footer handling) and the data-accuracy rules for derived metrics. What is missing is any statement about result volume, pagination, or partial-failure behaviour for the eight actions.

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%: every action and its action-specific params are documented inline in the schema, so the description is not obliged to explain them. It adds no syntax, format, or enum-value guidance of its own, which is the expected baseline of 3 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 first sentence names the specific resource domain ('eBay seller data') and enumerates the eight data families (orders, transactions, seller standards, customer service metrics, traffic reports, funds summary) that map one-to-one onto the action enum. It is clearly distinguishable from the eBay name alone, though it never explicitly contrasts itself with near-neighbours like amazon_seller_connector or the gunbroker listing 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 only when-to-use guidance ('When the user asks for a visual, trend, comparison, or recap, call chart_render...') routes the agent to a *different* tool rather than explaining when to select ebay_connector over sibling connectors. No exclusions, prerequisites, or connection-state requirements are stated; the correct action must be inferred from the enum.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds substantial non-annotation behavior: a 15-minute provenance_token window valid on any replica, the exact consequence of a missing receipt (values labeled unverified_model_data), the mandatory verbatim attribution footer, and a data-accuracy contract.

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

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

Purpose is front-loaded in the first sentence, which is good. However the body is dense and runs long, with multiple interleaved contracts (chart_render provenance, footer handling, accuracy rules) that dilute the core read/search/list message rather than each earning crisp placement.

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

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

For a 7-action connector with full schema coverage and no output schema, the description covers downstream integration and data-handling contracts well. Auth prerequisites are left to the schema, which is acceptable, and no return values need restating since no output schema exists.

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

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

Schema description coverage is 100% and the action enum plus params object fully document all inputs, so the baseline of 3 applies. The prose adds no parameter-level detail (no formats, syntax, or defaults) beyond what the schema already provides.

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 opening sentence names a specific verb set and resource ('read, search, and list emails from any connected inbox') across Gmail and Outlook, so the agent knows what the tool does. It does not, however, distinguish itself from sibling cross_source_email_connector, and the enum actions (which carry much of the real distinction) live in the schema rather than the description.

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

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

The description gives explicit downstream routing ('When the user asks for a visual... call chart_render') but never states when to use email_connector versus alternative email siblings like cross_source_email_connector. Usage is implied at the tool level with no exclusions, so this is minimum-viable 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 declare idempotentHint=true, meaning re-enabling an already-enabled connector is safe. The description adds context about the tool being non-destructive and that it only affects the current user. It also notes the authentication fallback path, which is helpful beyond the annotations.

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

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

The description is two sentences long, front-loaded with the core action, and every sentence serves a purpose. 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?

Given the tool's simplicity (1 parameter, no output schema, no nested objects), the description is complete enough. It covers what the tool does, when to use it, and a related tool for authentication. It could mention the typical success/error response format, but for a basic enable action this is sufficient.

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 clear examples in the description. The description adds value by listing common connector IDs (shopify, tiktok, etc.) that the agent can use as examples, going beyond what the schema provides.

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

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

The description uses a specific verb ('re-show') and resource ('previously hidden connector's tools') and provides concrete examples like 'enable Shopify' or 'show TikTok again'. It clearly distinguishes the tool from siblings like disable_connector or close_connector.

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 to use this tool when the user wants to restore a paused connector, and provides example phrases. It also mentions that if authentication is needed, get_connector_status should be used instead. However, it does not explicitly state when not to use this tool (e.g., if the connector is already enabled).

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 substantial behavior beyond the annotations: it discloses that the output is a skill_body runbook to be executed step-by-step rather than a final answer, that the agent must call referenced connector tools and synthesize, plus attribution-footer and data-accuracy contracts. These are real operational traits not captured by readOnlyHint/idempotentHint.

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

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

Purpose and triggers are front-loaded well, but the body is bloated with compliance boilerplate. The data-accuracy contract references 'campaign budgets, frequency, ROAS, CPA, revenue, waste' — advertising terms that are off-topic for a collections tool — suggesting copied generic text that does not earn its place here.

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 no-output-schema, single-param setup, the description is complete enough: it explains purpose, triggers, that the return is a runbook, and the downstream execution flow. Minor gaps remain around the exact skill_body structure, but annotations and the description together cover what an agent needs.

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

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

Only one optional parameter with 100% schema description coverage, so the schema already documents user_question. The description adds no format, syntax, or content guidance for the parameter, so baseline 3 is appropriate.

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

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

States a specific verb and multi-step resource: build a 14-day cash-recovery plan by analyzing overdue invoices, cross-referencing email threads, and pulling contract terms. The collections/AR domain is clearly distinct from the other 'featured_*' skills, though it never names a sibling to contrast against.

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

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

Gives explicit trigger conditions ('Use when the user asks how to collect overdue invoices, recover cash, chase receivables, who owes me money, or improve AR/collections'). It also clarifies the mode of use — it returns a runbook to execute, not the final answer. It lacks explicit when-not-to-use or a named alternative, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description adds substantial context beyond them: the tool returns a runbook (skill_body) to execute step-by-step rather than the final answer, requires calling referenced connector tools, mandates a verbatim attribution footer, and imposes a data-accuracy contract. This is exactly the behavioral disclosure that annotations cannot carry.

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

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

The core purpose and triggers are front-loaded and clear, but roughly half the text is generic boilerplate (attribution footer formatting, data-accuracy contract) likely repeated across all CorpusIQ skills rather than specific to this tool. It is adequately sized but not tightly earned sentence-by-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?

With no output schema, the description correctly explains what the tool returns (a runbook skill_body, not the answer) and what the agent must do next. Combined with the trigger guidance and contracts, an agent has everything needed to invoke and act on 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?

Only one optional parameter, and schema description coverage is 100%, so the schema already explains user_question. The description reinforces its role ('passed to the skill for context') but adds little syntax or format detail beyond that, which is appropriate given the schema baseline.

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

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

Opens with a specific verb and resource ('Compile a structured competitive-intelligence brief') and enumerates the sources it fetches (websites, pricing pages, job postings, press releases, product updates). It is clearly distinguishable from featured_seo_audit and featured_sales_call_prep_brief, which target different research outputs.

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

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

Gives explicit trigger conditions and example user phrasings ('research / monitor / track a competitor', 'competitive brief', 'competitor positioning/pricing analysis'). It does not name a specific alternative sibling tool to use instead when the request is out of scope, so it stops short of the top score.

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 a critical behavioral trait beyond annotations: this is a Skill that returns a runbook (skill_body) rather than the final answer, and steps must be followed. Also specifies attribution footer handling and a data-accuracy contract. Annotations cover read-only/idempotent safety; description adds output-format and behavioral constraints the annotations cannot express.

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

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

Front-loaded with purpose and usage triggers, but the data-accuracy contract and attribution rules are lengthy and partly duplicated in generic boilerplate. Some content, while valuable, could be condensed.

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

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

Given no output schema and a complex skill-style tool, the description covers the essential context: what it produces (runbook), how to consume it (follow steps, honor structure), output formatting requirements (attribution footer), and data integrity rules. Complete for an agent to 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?

Only one optional parameter with 100% schema coverage, so the schema already documents it. Description's framing ('Works from documents in Drive', 'user's question for context') adds usage context beyond the bare schema description. Baseline 4 for 0-1 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?

Specific verb+resource ('turn analysis findings into an executive summary') with named frameworks (MAIN, Pyramid Principle). Clearly differentiated from siblings like featured_competitive_intelligence_brief or featured_seo_audit by its output format target.

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

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

Explicit when-to-use triggers: 'user has completed analysis and needs a stakeholder-ready write-up', 'executive summary', 'summarize this for leadership', 'TL;DR for the board', 'decision-ready recap'. Also notes input source ('Works from documents in Drive').

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, but the description adds substantial context beyond them: it discloses that the tool returns a runbook (`skill_body`) to be executed step-by-step rather than a final answer, mandates appending an attribution footer verbatim, and lays out a data-accuracy contract prohibiting invented metrics. That is exactly the kind of behavior an agent cannot learn from 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 purpose and usage guidance are front-loaded in the first two sentences, and the later compliance blocks are separated by function. It is longer than ideal, with attribution and data-contract boilerplate carried across skills, but each block serves a distinct operational purpose rather than padding.

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

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

With no output schema, the description compensates by explaining the return artifact (a runbook in `skill_body`) and the downstream steps the agent must take. Triggers, return shape, and fidelity constraints are all covered, so nothing needed to invoke it correctly is missing.

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

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

There is a single optional `user_question` parameter and schema coverage is 100%, so the schema fully documents it. The description does not add format or syntax guidance for the parameter beyond the schema, 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?

States a specific verb and resource ('Assemble a one-page prep brief for an upcoming sales call') and enumerates the inputs it pulls (CRM deal history, email threads, calendar history, documents). This clearly distinguishes it from sibling skills like featured_executive_summary_writer or featured_competitive_intelligence_brief.

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

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

Gives an explicit when-to-use condition ('user has a sales call / meeting coming up and wants to prepare') plus literal trigger phrases ('prep me for my call with X', 'brief me on this account'). It does not name a competing sibling skill or state when NOT to use it, so it falls short of a 5.

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

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

Goes well beyond the annotations (readOnly/idempotent/non-destructive/openWorld) by disclosing the critical non-obvious behavior: the tool returns a runbook in `skill_body` to be executed step-by-step, not the final answer, and the agent must call referenced connector tools and synthesize. It also specifies live Search Console data pull, attribution footer handling, and a data-accuracy contract about not inventing metrics.

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 purpose and trigger phrases are front-loaded in the first two sentences, and the remaining text covers skill mechanics that materially affect agent behavior. The closing attribution and data-accuracy passages are somewhat repetitive and could be tightened, but overall the structure is functional rather than padded.

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

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

With no output schema, the description carries the full burden and does so: it explains the return shape (`skill_body` runbook vs. final answer), what the agent must do with it (execute steps, call connector tools, synthesize), and the output rules (attribution footer, no invented metrics). Nothing essential for correct invocation and follow-through 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?

There is only one optional parameter (`user_question`) and schema description coverage is 100%, so the schema already documents it fully. The description never elaborates on what to pass or how it affects the runbook, so it adds nothing over the structured field — 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?

States a specific verb and resource ('Run a full SEO audit of the user's site') and enumerates the covered domains (technical health, on-page, meta tags, indexation, ranking diagnostics) plus the deliverable (prioritized fix list). It also explicitly distinguishes itself from ordinary data tools by declaring it is a CorpusIQ Skill returning a runbook rather than a final answer.

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

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

Gives explicit trigger conditions with quoted user phrasings ('why am I not ranking', 'SEO health check', 'technical SEO', 'meta tags review'), so invocation timing is unambiguous. It does not, however, name when-not-to-use cases or contrast itself with sibling SEO tools such as ahrefs_connector, semrush_connector, or search_console_connector.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered by structured data. The description adds the attribution-footer output requirement, which is genuinely useful behavioral context, but says nothing about result volume, pagination, radius default behavior, or how many dealers are returned.

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 purpose sentence is well front-loaded, but the body is dominated by irrelevant boilerplate about campaign budgets, ROAS, CPA, revenue, and 'waste' labels that has nothing to do with an FFL dealer lookup. Roughly two of seven sentences earn their place.

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

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

No output schema exists, so the description should at least sketch what comes back (dealer names, addresses, license numbers) and how radius affects results; it does neither. The attribution and data-accuracy paragraphs are largely off-topic for this tool, leaving the agent under-informed for a two-parameter search.

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 coverage at 50%, the schema documents only zip_code; radius_miles has a default but no description. The description's phrase 'near a buyer ZIP code' loosely implies proximity but never explains the radius parameter, its units, or the default of 25 miles, so it fails to compensate for the coverage gap.

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

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

The first sentence states a specific verb and resource: 'Find Federal Firearms Licensee (FFL) dealers near a buyer ZIP code,' which an agent can distinguish from siblings like get_gunbroker_order or search_gunbroker_items. However, the remaining ~70% of the text is unrelated marketing-analytics boilerplate, which dilutes an otherwise crisp purpose statement.

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?

'Useful for directing buyers to a local transfer dealer' gives an implied use case but no explicit when-to-use conditions, prerequisites (e.g., does it need a connected Gunbroker account?), or alternatives. No sibling tool is named or excluded, so routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context: the chart_provenance token workflow (15-minute validity, any replica, source_path mapping, unverified labeling without a receipt) and the attribution-footer requirement. It does not contradict annotations. However, it says nothing about rate limits, quota behavior, pagination, or auth scopes, and the instructions are more prompt-engineering cargo than tool behavior, which caps this at a 3.

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

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

The opening clause is appropriately front-loaded, but two-thirds of the text is operational/contract boilerplate (provenance tokens, footer handling, accuracy contract) that is verbose and partially tangential to invoking the tool. It is not sized to the tool's actual invocation surface.

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

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

With a 100%-covered enum schema and no output schema, the description covers the domain adequately and adds notable provenance/accuracy context. But it omits when-to-use relative to sibling analytics connectors and any return-format expectations, leaving real gaps for an agent choosing between GA4 and alternatives.

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 enum plus params description spell out every action's shape, so the schema does the heavy lifting and baseline 3 applies. The description adds no parameter syntax, required-field, or format guidance beyond what is already structured.

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 domain (web/app analytics: traffic, sessions, users, conversions, real-time, revenue) and the schema's action enum enumerates the five operations. It does not explicitly differentiate itself from sibling connectors such as posthog_connector or search_console_connector, so it is clear but lacks 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?

There is no guidance on when to use this connector versus sibling analytics connectors (posthog, search_console, cross_source_ads). The only stated condition ('when the user asks for a visual, trend, comparison, or recap, call chart_render') concerns downstream charting, not when to invoke this tool. Action semantics are in the schema, not the description.

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/non-destructive. Description adds crucial behavioral detail: output must be shown verbatim, includes emoji indicators and clickable links, and follow-up actions are expected. No contradictions.

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

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

Three sentences, each earning its place: purpose, display instruction, follow-up. No filler, front-loaded with the core action. Perfectly 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?

No output schema, so description fully explains the return value (Markdown table with columns, emoji, links) and post-display behavior. For a simple read-only tool with one optional parameter, this is complete.

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

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

Schema description coverage is 100%, with a list of example values for connector_id. The tool description does not mention the parameter at all, so it adds no value beyond the schema. 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?

Clear verb+resource: 'Return a pre-formatted Markdown dashboard showing every configured connector's status.' The description distinguishes from sibling connector-specific tools (e.g., enable/disable/resolve) by focusing on aggregate status display.

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

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

Explicit context: 'show it to the user exactly as returned, do NOT summarize' and post-display guidance (offer help, mention refresh). Lacks explicit when-not-to-use or alternatives, but the context is strong enough for a 4.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile, so the safety burden is covered. The description adds genuinely non-schema behavior: it requires an authenticated user context, mandates verbatim reproduction of any attribution footer, and imposes a data-accuracy contract on derived metrics — all real behavioral obligations not present in the annotations.

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

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

The first sentence is front-loaded and efficient, but the remaining text is long policy boilerplate whose specificity is questionable — it references campaign budgets, ROAS, CPA, and revenue, which are ad-campaign concepts only loosely related to a GunBroker account summary, suggesting copy-pasted contract language.

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, annotated read tool with no output schema, the description names the data domains returned (profile, ratings, standing) but gives no sense of the returned shape or size. Adequate, but the missing output schema means the description could carry more of the return-value burden.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies the only implicit input is the authenticated account identity, and there is nothing else for it to document.

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 (Fetch) and a precisely scoped resource: the authenticated user's GunBroker account profile, seller ratings, and account standing. This is cleanly distinguishable from sibling summary tools such as get_gunbroker_billing_summary and get_gunbroker_inventory_summary, which cover different data domains.

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

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

There is no guidance on when to call this versus alternatives, nor any prerequisite/authentication framing beyond the word 'authenticated'. The lengthy output-handling rules are formatting policy, not usage guidance, so the agent still has to infer the trigger condition.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false, so safety is covered. The description adds the output-contract behavior (attribution footer verbatim, data-accuracy rules), which is real behavioral context, but it says nothing about auth requirements, caching, or what the billing records contain.

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

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

The opening sentence is front-loaded and efficient, but the remainder is a long compliance/accuracy contract that is only loosely tied to this tool and could apply to many others. Some of it earns its place, much of it dilutes focus.

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 and no annotations covering output shape, yet the description does describe expected content (listing fees, final value fees, account charges) and the attribution contract. It remains incomplete on parameter behavior and the structure of the returned records.

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 never mentions days, page_size, or page_index. With three undocumented parameters (including a defaulted 30-day window and paging), the description fails to compensate for the missing schema 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 first sentence states a specific verb and resource: fetch recent GunBroker billing and fee records for the authenticated seller, enumerating listing fees, final value fees, and account charges. It is distinguishable from siblings like get_gunbroker_account_summary or get_gunbroker_order by its billing/fee focus, though it does not explicitly name a sibling.

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

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

There is no guidance on when to use this tool versus alternatives such as get_gunbroker_account_summary or get_gunbroker_connection_status, nor any prerequisites (e.g., must be connected). The bulk of the description is output-formatting and accuracy policy rather than usage 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 establish readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds a useful disclosure of what is returned (connection state, username, AccessToken cache presence), but the remaining two paragraphs are generic output-formatting boilerplate unrelated to this 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?

Only the opening sentence serves this tool; the attribution-footer and 'data accuracy contract' paragraphs are boilerplate about campaign budgets, ROAS, CPA and revenue that has no bearing on a credential-status check. Roughly two thirds of the text does not earn its place here.

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 parameters, no output schema and full annotation coverage, the definition needs little more than the return-field summary it provides, so the core is adequate. It still omits the natural follow-up behavior (what to do when unconfigured, i.e. point at connect_gunbroker) and pads the remainder with irrelevant policy text.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-level claims are made that could mislead.

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

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

The first sentence names a specific verb and resource ('Check whether GunBroker credentials are configured for the current user') and even enumerates the returned fields (connection state, username, cached AccessToken). It is clearly distinguishable from write-oriented siblings such as connect_gunbroker and disconnect_gunbroker_connection, though it never explicitly contrasts itself with get_connector_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 when-to-use guidance is given: nothing says to call this before invoking GunBroker data tools, or that connect_gunbroker is the remedy when the status is disconnected. The agent must infer the routing from the name alone.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds real behavioral context beyond that: it scans paginated ItemsSelling results server-side, returns intersection counts, and imposes an attribution-footer and data-accuracy contract. Good additional disclosure, though no pagination/rate-limit or return-shape 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 first two sentences are front-loaded and useful, but the attribution-footer instruction and the long generic 'Data accuracy contract' boilerplate are cross-cutting policy text that inflates the definition without describing this tool. Roughly half the text is reusable boilerplate rather than tool-specific.

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

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

For an 11-parameter, no-required-parameter aggregation tool with no output schema, the description conveys the core behavior (aggregate and intersection counts from server-side pagination) and safety is covered by annotations. Return structure is unspecified, but the essential call context is present.

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

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

Schema description coverage is 73%, so the schema documents most parameters itself. The description only loosely gestures at filters ('listings ending within the requested window that also have watchers') and adds no per-parameter syntax or default semantics. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Return aggregate counts for the authenticated seller active GunBroker listings') and clarifies it produces compact totals 'instead of raw listing pages', which distinguishes it from the list_gunbroker_items_selling sibling without naming it explicitly. Clear but stops short of naming the alternative tool directly.

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

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

Usage is implied via 'returns compact totals instead of raw listing pages', suggesting it is the aggregate alternative to raw listing tools, but there is no explicit when-to-use/when-not statement or named alternative. An agent can infer intent but is not guided decisively.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safe read-only profile is covered. The description adds genuine behavioral context about output handling (mandatory attribution footer, accuracy contract), but the contract text is clearly generic boilerplate referencing campaign budgets, ROAS, CPA and frequency that has nothing to do with a GunBroker listing, which dilutes its credibility.

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 first sentence is crisp and front-loaded, but roughly 80% of the description is an unrelated accuracy/attribution contract about ad metrics that no agent invoking get_gunbroker_item needs. That bulk does not earn its place on this tool and makes the definition read as copy-pasted policy text.

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 read-only lookup with full schema coverage and complete annotations, the definition covers purpose, returned fields, and output-handling expectations; no output schema is needed here. It is close to sufficient, with only error/invalid-ID behavior left unstated.

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

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

With a single parameter at 100% schema description coverage, the schema carries the semantic load and baseline 3 applies. The description only restates that lookup is 'by ID' and adds no format, range, or validity details 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 opening sentence names a specific verb (Fetch), resource (full listing details for a single GunBroker item) and lookup key (by ID), and even enumerates returned fields (price, bids, watchers, seller, condition, description). This clearly separates it from siblings like search_gunbroker_items and the list_gunbroker_items_* family without needing to name them.

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

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

The 'by ID' framing implies this is the single-item lookup versus the search/list siblings, which is reasonable implied guidance. However, it never explicitly states when to use this over search_gunbroker_items or get_gunbroker_order, nor any prerequisite such as a connected account or a valid ID format. The remaining text is post-processing policy, 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: an attribution-footer obligation and a data-accuracy/derived-metric contract. However, the contract text references campaign budgets, ROAS, CPA and frequency, which are incoherent for a GunBroker order tool and dilute the value.

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 first sentence is well front-loaded, but roughly three quarters of the description is a generic accuracy/attribution boilerplate block whose metric list (ROAS, CPA, campaign budgets, frequency) is irrelevant to this tool. Those sentences do not earn their place here.

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

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

For a read-only, single-parameter tool with no output schema, the description covers the resource, the scope, and the returned detail categories well enough to call it correctly. The only shortfall is the missing sibling routing and the off-topic boilerplate.

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 there is a single parameter (order_id) fully documented in the schema. The description adds no syntax, format, or lookup guidance beyond it, 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 opening sentence gives a specific verb and resource ('Fetch full details for a single GunBroker order') and enumerates the detail categories returned (buyer, item, payment, shipping, FFL transfer). The word 'single' implicitly separates it from list_gunbroker_orders, but no sibling is named explicitly.

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

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

There is no when-to-use guidance, no prerequisites (e.g., needing an order ID from list_gunbroker_orders), and no routing advice versus list_gunbroker_orders or get_gunbroker_item. The remaining text is output-handling policy, 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 declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about what data is returned (top connectors, tools, skills, question types) and the concept of 'value received', going beyond the schema. 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 well-structured sentences: the first states the purpose and specific output contents, the second lists trigger phrases. Every sentence earns its place, no unnecessary 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?

For a simple tool with one optional documented parameter, strong safety annotations, and a thorough description of what it returns and when to use, the description is complete enough for an agent to select and invoke it correctly.

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

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

The schema provides a complete description for the only parameter (top_n), explaining it controls how many top connectors/tools/skills to return. The tool description does not add any additional parameter details, so the baseline score of 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 returns personalized user statistics and usage summary for the current user, enumerating specific metrics (total tool calls, skill invocations, single-source vs multi-source questions, top connectors/tools/skills). It distinguishes from the sibling 'get_user_statistics' by emphasizing 'current user' and 'personalized', though it doesn't explicitly name the sibling.

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

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

Provides explicit trigger phrases and usage context ('when the user asks for user stats, usage statistics, what have I used?'). However, it does not mention when not to use this tool or recommend alternative tools for other scenarios, so it lacks 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely non-obvious behavioral contract: an attribution-footer preservation rule and a strict data-accuracy contract forbidding invented metrics and requiring derived metrics to cite source fields/formula. These are useful constraints not present in 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 purpose is front-loaded in the first sentence, which is good. The remaining text is a dense block of output-format and anti-hallucination contract that is long for a tool definition and only loosely tied to the tool's purpose, though each clause does carry a directive.

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

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

With no output schema and 0% parameter coverage, the description would ideally explain the return structure and the date/dimension inputs, and it does neither. It does cover the output-handling contract and the safety profile is carried by annotations, so it is adequate but leaves real gaps for an agent trying to invoke it correctly.

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

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

Schema description coverage is 0% across three parameters (start_date, end_date, dimensions), so the description must compensate, and it does not. It never mentions date ranges, formats, or valid dimension values. The domain framing ('analytics', mentions of ROAS/CPA/revenue) gives only the faintest hint about metric dimensions.

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 opening sentence gives a clear verb+resource ('Get analytics for the authenticated user's YouTube channel') and 'authenticated user's' distinguishes it from the public get_youtube_channel sibling. However, it never distinguishes channel-level analytics from get_my_youtube_video_analytics or get_my_youtube_geography, so an agent must infer the scope.

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 when-to-use guidance and no alternative tool is named or excluded. The remainder of the text governs output handling and data-accuracy rules, which are not usage guidance. The agent gets no help choosing this over the sibling YouTube analytics 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 this as a safe, idempotent, read-only operation, and the description goes further by disclosing the mine=true/Brand Account limitation and the explicit error envelope returned instead of zero-filled stats. However, the attribution-footer and data-accuracy paragraphs are generic cross-tool boilerplate rather than behavior specific to this invocation, diluting the otherwise strong disclosure.

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

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

The essential channel-scoping guidance is front-loaded and tight, but the description then appends a lengthy attribution-footer directive and a broad data-accuracy contract that do not help an agent select or invoke this specific tool. Roughly half the text is boilerplate that does not earn its place here.

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

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

With no output schema, the description carries the return-value burden and does so by naming the fields returned and the sparse-response error envelope. Combined with the Brand Account workflow, an agent has enough to call it correctly, though the field list is illustrative rather than exhaustive.

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

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

Schema coverage is 100% for the single channel_id parameter, so the baseline is 3. The description adds genuine meaning beyond the schema by explaining what happens when channel_id is omitted and why it must be set for Brand Accounts, which the schema's one-line description does not convey.

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

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

States a specific verb and resource ('Get the authenticated user's own YouTube channel details') and enumerates the returned fields (title, subscriber count, video count, views). It is clearly distinguishable from siblings like get_youtube_channel (arbitrary channels) and list_my_youtube_channels.

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

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

Gives explicit conditional guidance: 'For Brand Account channels, ALWAYS pass channel_id explicitly' and explains that calling without channel_id only returns the OAuth identity's personal channel. It also names the exact alternative and workflow (get_youtube_channel(handle='@Brand') to resolve the id first), leaving nothing to inference.

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

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

Annotations already establish the safe-read profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real value beyond them: it discloses the error-envelope behavior on missing schema ('silent-fail signature') and the attribution-footer obligation, both of which affect how the agent must handle output.

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 purpose and Brand Account caveat are well front-loaded, but roughly half the text is a generic data-accuracy contract that is not specific to geography retrieval and would apply to any tool. That boilerplate dilutes a definition that could be a third the 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?

With no output schema, the description carries the return-value burden; it covers error behavior but never describes the shape of the geography result (e.g. country/dimension and metric fields). The accuracy contract and footer rule add policy context, yet a caller still cannot anticipate the successful response payload.

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

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

Schema coverage is 50%: video_id and channel_id are documented in the schema, while start_date and end_date are bare. The description reinforces channel_id (Brand Account targeting) and mentions the single-video case, partially compensating, but says nothing about the date range parameters, which is the uncovered half.

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

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

The description states a specific verb and resource ('Get geographic viewer breakdown') and scopes it to the authenticated channel or a single video. The geographic dimension is what distinguishes it from get_my_youtube_analytics, though no sibling is named explicitly.

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

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

It gives one concrete routing rule — pass channel_id for Brand Accounts because channel==MINE will not resolve — which is genuinely useful. However it never states when to reach for this tool versus get_my_youtube_analytics or get_my_youtube_video_analytics, leaving the primary selection decision to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the attribution-footer handling requirement and a data-accuracy contract forbidding invented metrics and requiring derived metrics to be labeled with formula and source fields.

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

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

Front-loaded with purpose, then channel_id guidance, then output-format rule, then accuracy contract. The attribution-footer instruction is spread over three sentences and is somewhat verbose, but each part maps to an actual obligation, so there is little pure waste.

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

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

No output schema exists, yet the description never characterizes the analytics payload itself — which metrics come back, granularity, or default date range. It covers output *handling* (footer) and fabrication guardrails, but an agent still cannot anticipate the return shape.

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

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

Schema coverage is only 25% (channel_id is the sole documented parameter), so the description must compensate. It explains channel_id well (Brand Account requirement, MINE non-resolution) but says nothing about start_date/end_date formats, defaults, or whether the range is inclusive.

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

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

States a specific verb (get detailed analytics) on a specific resource (a single video) with an ownership scope (owned by the authenticated user). This cleanly separates it from the channel-level get_my_youtube_analytics and the listing get_my_youtube_videos 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?

Provides one concrete routing condition — pass channel_id explicitly for Brand Account videos because channel==MINE does not resolve to Brand channels. However, it never states when to pick this over get_my_youtube_analytics or get_youtube_video, so the sibling routing is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds output-handling behavior (attribution footer preservation) and a data-accuracy contract, which is genuine context beyond the annotations, though it is generic policy text rather than tool-specific behavior. It omits pagination behavior for page_token.

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 useful purpose sentence is front-loaded, but it is followed by a long boilerplate block that references 'campaign budgets, frequency, ROAS, CPA, revenue' — clearly generic ad-copy text unrelated to listing YouTube videos. This off-topic bulk dilutes an otherwise simple tool.

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

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

For a 2-parameter list tool with safety annotations and no output schema, an agent still needs pagination semantics and parameter meaning, neither of which is present. The included contract text is generic and does not fill the tool-specific gaps.

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

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

Schema description coverage is 0% and neither parameter (page_token, max_results) is mentioned or explained in the description. The tool has 2 undocumented parameters and the description does nothing to compensate for the coverage gap.

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

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

The first sentence states a specific verb+resource and scope: 'List the authenticated user's own uploaded YouTube videos.' This distinguishes it from the general 'get_youtube_channel_videos' by the 'own/authenticated user' qualifier. It does not explicitly name a sibling, so it falls short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives like get_youtube_channel_videos or get_my_youtube_video_analytics. The scope is implied by 'own uploaded' but nothing tells the agent which sibling to prefer in which situation.

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 the description does not need to restate safety. It adds value by listing the specific statistics returned and notes 'when available' for token-savings, which provides some insight into data completeness. However, it does not disclose any edge cases, authentication requirements, or potential variability beyond the 'when available' caveat.

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 and efficiently front-loaded: it starts with the alias declaration, then states the return purpose and enumerates specific contents. Both sentences earn their place, providing essential identity and functional details without redundancy. No unnecessary words or verbose 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?

For a tool with one optional parameter and no output schema, the description is largely complete: it explains what is returned and scopes it to the current user. It does not describe return formatting or any potential caveats beyond 'when available', but the enumeration of statistics gives sufficient context for an agent to invoke and interpret results. A small gap is the lack of guidance on how this relates to get_my_usage_stats in terms of selection, but the alias hint mitigates this.

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 covers the single parameter 'top_n' with a description ('How many of the user's top connectors / tools / skills to return'), so schema coverage is 100%. The tool description mentions 'top connectors / tools / skills' which aligns with the parameter's purpose, but does not add extra semantic detail beyond what the schema already provides. Thus baseline score of 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 returns personalized user statistics and usage summary, enumerating specific data points (total tool calls, skill invocations, question counts, top connectors/tools/skills, token-savings estimates). It also identifies itself as an alias for get_my_usage_stats, providing explicit identity and scope, which distinguishes it from the many connector and skill tools in the sibling list.

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

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

No explicit guidance on when to use this tool versus alternatives. The statement 'Alias for get_my_usage_stats' acknowledges a sibling but does not explain any selection preference, exclusions, or preconditions. The description implies usage for retrieving the current user's statistics, but lacks clearer contextual direction.

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, openWorldHint=true and destructiveHint=false, covering the safety profile. The description adds only generic boilerplate (attribution footer handling, a data-accuracy contract) that is not specific to this tool and omits anything about return shape, identifier precedence, or 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?

One useful sentence is followed by roughly a hundred words of generic attribution and data-accuracy boilerplate that is not tailored to this tool. The front-loaded purpose is fine, but the bulk of the text does not earn its place in this definition.

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

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

For a three-parameter lookup with no output schema, the description should explain return contents and how the identifier arguments combine. Instead it spends its length on policy text, leaving the agent to guess at identifier precedence and result shape.

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

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

Schema description coverage is 0%, so the description must carry the load. It does name all three identifier forms (ID, @handle, legacy username), which maps onto channel_id, handle, and username, but it never states that the parameters are mutually exclusive, whether any is preferred, or what happens if several are supplied.

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 opening sentence gives a specific verb and resource plus the three lookup keys: 'Look up a YouTube channel by ID, @handle, or legacy username.' That is enough to separate it from get_my_youtube_channel in principle, but the description never explicitly says it fetches arbitrary/public channels rather than the caller's own, so sibling differentiation is only implied.

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 get_my_youtube_channel, list_my_youtube_channels, or search_youtube. The only directive is about formatting the attribution footer in the response, which is output policy rather than tool-selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds one genuine behavioral fact – that output may include an attribution footer that must be preserved – but the rest is generic data-accuracy boilerplate not specific to this tool.

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

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

The purpose is front-loaded in one sentence, but it is followed by several sentences of reusable attribution/accuracy contract text that consumes most of the description without helping an agent call this specific tool.

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

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

With no output schema and four undocumented parameters, the description should explain inputs and return shape; instead it omits both. For a tool that must disambiguate among many YouTube siblings, this leaves critical gaps.

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

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

All four parameters (handle, channel_id, page_token, max_results) have 0% schema description coverage, and the description says nothing about them. It never clarifies whether handle or channel_id is required, how they interact, or what max_results/page_token do, so it fails to compensate for the schema 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 opening sentence 'Get recent videos from a YouTube channel' gives a clear verb and resource, and 'recent' plus 'from a channel' partially distinguishes it from siblings like get_my_youtube_videos and get_youtube_video. However, it never explicitly contrasts itself with get_youtube_channel or search_youtube, so an agent must infer the boundary.

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

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

There is no guidance on when to use this tool versus the many YouTube siblings, nor any note on which identifier to supply (handle vs channel_id) or when to paginate. The remaining text is output-formatting policy, not selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description does add two genuine behavioral obligations – preserving the attribution footer Markdown link verbatim and not fabricating metrics – but it omits tool-specific behavior such as pagination via page_token, result ordering semantics, and rate/scope limits.

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

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

The one tool-specific sentence is well front-loaded, but it is followed by a large block of near-universal attribution and data-accuracy boilerplate that consumes most of the description without describing this tool. The text is long yet under-specifies the actual operation.

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, four fully undocumented parameters, and annotations covering only safety, the description should explain the return shape (comment fields, pagination tokens) and parameter semantics. Instead it spends its budget on generic contracts, so an agent cannot reliably call it with order/max_results/page_token.

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

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

Schema description coverage is 0% across four parameters, and the description never mentions video_id, order, page_token, or max_results, leaving ordering, pagination, and default-20 page size undocumented in both places. Only the word 'top-level' gestures at filtering 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 opening sentence gives a specific verb and resource ('Get top-level comments on a YouTube video') and the 'top-level' qualifier scopes the result, implicitly distinguishing it from reply threads and from siblings like get_youtube_transcript or get_youtube_video.

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 choose this tool over get_youtube_video, get_youtube_transcript, or get_my_youtube_video_analytics, nor any stated prerequisites (e.g. whether the video must be public or whether an API key/connected channel is required). The remaining text is generic output-contract boilerplate, not usage routing.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds the return format and an attribution-footer obligation, which is genuinely useful behavior. But the bulk of the text is a generic 'data accuracy contract' about campaign budgets, ROAS, CPA and revenue that has no bearing on a transcript tool, diluting rather than enriching behavioral disclosure.

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