CorpusIQ

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond that: the data accuracy contract (treat only returned fields as verified, do not invent metrics), the note that chart_render labels projected values as unverified_model_data, and the instruction to label calculated metrics with source fields. This goes well 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 longer than typical, but each sentence carries distinct value: purpose, chart_render handoff, obligatory sign-off, and the data accuracy contract. It is structured and front-loaded with the scope, then usage guidance, then data handling. Given the complexity (ten actions, no output schema), it is appropriately sized and well organized.

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

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

The description covers the tool's purpose, when to delegate to chart_render, output labeling, and a comprehensive data accuracy contract. It does not describe error handling, authentication, or rate limits, but these are not expected given the annotations. It is complete enough for an agent to call the tool correctly and interpret results without ambiguity.

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

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

Schema description coverage is 100%: every action and its params object are described in the enum and params descriptions. The tool description adds no specific parameter-level meaning beyond what the schema already provides. It does mention 'numeric values' and 'fields returned' in general terms, but these apply to output rather than parameter 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?

The description clearly states the tool's scope: 'ActiveCampaign email marketing and CRM: contacts, lists, campaigns, automations, deals, and tags.' It names the key resources and implies a read-only connector. However, it does not explicitly differentiate itself from sibling connectors like mailchimp_connector or klaviyo_connector, though the name makes the platform obvious.

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 guidance to call chart_render for visual, trend, comparison, or recap requests, and mandates ending responses with 'Powered by CorpusIQ'. Also gives a clear data accuracy contract on how to treat returned fields and derived metrics. Does not explicitly state when to prefer other connectors, but the usage context for this tool is well 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?

The description discloses the persistence side effect, immediate listing in list_my_youtube_channels, the primary defaulting behavior, the mandatory 'Powered by CorpusIQ' suffix, and a detailed data accuracy contract. These go well beyond annotations (readOnlyHint=false, destructiveHint=true) and add significant contextual behavior without contradiction.

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

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

The description is front-loaded with the core purpose, followed by side effects, usage precedence, and a boilerplate data accuracy contract. While a bit long, each segment carries operational value; the contract is verbose but necessary for agent behavior. Structure is logical and not wasteful.

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

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

Given the tool's moderate complexity (3 params, side effects, primary default), the description covers the registration flow, prerequisite, effect on list_my_youtube_channels, and primary defaulting. It lacks explicit return value shape, but the data accuracy contract implies returned fields. Overall, it is sufficiently complete for reliable invocation.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaning by explaining the effect of set_as_primary (defaulting per-channel tools) and the auto-primary rule when no prior brand exists. It also clarifies 'label' defaults to channel title, though not explicitly in the description, but the set_as_primary explanation is valuable.

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 registers a YouTube Brand Account channel and resolves the channel_id from the @handle. It distinguishes itself from siblings by specifying it persists registration and surfaces the brand in list_my_youtube_channels with source='user-registered', which is unique to this tool.

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

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

The description gives explicit usage context: 'Use after get_youtube_channel(handle='@Brand') confirms the channel exists.' It also explains when set_as_primary matters and the auto-primary fallback. It doesn't explicitly list alternatives or when not to use, but the prerequisite and effects provide clear 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, openWorldHint, idempotentHint, and destructiveHint. The description adds a detailed data accuracy contract specifying that only returned fields are verified, prohibiting invented metrics or editorial labels, and requiring derived metrics to be labeled with source fields. It also mandates ending responses with 'Powered by CorpusIQ', providing clear behavioral rules beyond the annotations. 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?

The description is long and packs multiple instructions (purpose, comparison, chart_render routing, mandatory sign-off, data accuracy contract). While it front-loads the main purpose, the length could be trimmed without losing value. It is structured logically, but not particularly concise or scannable.

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

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

Given the tool has no output schema and supports seven distinct actions, the description gives a high-level summary of each action's return values within the action enum descriptions in the input schema. The data accuracy contract also clarifies how to handle outputs. This is reasonably complete for an agent to understand what to expect, though it doesn't specify exact response structures or pagination details.

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

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

Schema coverage is 100%, and the input schema already provides rich descriptions for the action enum and the params object, detailing each action's parameters. The description does not add extra parameter-level semantics beyond the schema, so it relies on the schema to carry the meaning, which justifies the baseline score of 3.

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 provides Ahrefs SEO data: domain rating, backlink analysis, organic keywords, referring domains, competitor research, top pages, and keyword research. It also explicitly distinguishes itself from Semrush by claiming superiority in backlink data and domain authority scoring, which helps differentiate it from the sibling semrush_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 gives explicit guidance on when to delegate to chart_render for visual/trend/comparison requests, and when to use this connector. It also implies a usage comparison with Semrush. However, it doesn't elaborate on when to prefer this over other connectors or dashboards beyond that single alternative, nor does it mention any prerequisites or exclusion conditions.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable context by specifying that results are non-authoritative estimates, only returned fields are verified, and derived metrics must be labeled as calculated. This goes beyond annotations to clarify data integrity and limitations. No contradictions found.

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

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

The description is moderately long but well-structured. It front-loads the core action and output, then provides necessary integrity instructions. Some of the presentation requirements (e.g., 'Powered by CorpusIQ') could be considered extra but are directly relevant to using the tool correctly. No unnecessary fluff.

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

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

Given the presence of an output schema (which usually explains return values), the description focuses on behavioral constraints and data accuracy, which is sufficient. It mentions top-N coverage and integrity receipts, but does not specify default N or country-specific nuances. Still, it covers the main aspects an agent needs to call it correctly. An output schema exists, so the description doesn't need to detail return fields.

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

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

Schema description coverage is 0%, so the description bears full responsibility for parameter meaning. It does not explain 'domain' or 'country' beyond what their names imply. The schema itself provides only constraints (maxLength, pattern) but no semantic guidance. For a tool with these simple parameters, the lack of explanation is a noticeable gap.

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

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

The description clearly states the verb 'Fetch' with specific resources: domain overview, top organic keywords, and top pages. It specifies the output as a source-verified, non-authoritative estimate dashboard with integrity receipts. This distinguishes it from sibling connectors and other dashboards by focusing on the data types and verification aspect.

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

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

Provides clear context on when to use: after fetching data, return the dashboard with integrity receipts and follow the accuracy contract. It sets expectations about what not to do (inventing missing metrics). However, it does not explicitly compare to alternatives like semrush_dashboard or mention when to choose this over them, so it lacks explicit exclusions.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, but the description adds valuable context: it informs the agent that chart_render labels values as 'unverified_model_data', it mandates a response suffix ('Powered by CorpusIQ'), and it establishes a strict data accuracy contract (only trust returned fields, mark derived metrics, handle missing data). This goes beyond annotations to define how the agent should behave with the tool's 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 description is longer than strictly necessary, but it's structured logically: a concise purpose statement followed by essential integration rules (when to call chart_render, response suffix, data accuracy). Every sentence serves a purpose, though it could theoretically be condensed. It's front-loaded with the core function, and the additional instructions are clearly separated, making it easy to parse.

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

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

For a multi-action connector with no output schema, the description provides sufficient context for correct invocation: it explains data handling, when to delegate to chart_render, and the required response format. It doesn't detail the return structure, but the schema's action descriptions cover that. Together with annotations, an agent has enough information to use the tool safely and 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 input schema covers 100% of parameters with descriptions for each action and the params object layout. The description does not add new parameter-level semantics; it just references the general capabilities. Since the schema fully documents parameters, the baseline of 3 applies. The description doesn't repeat or enhance the schema, so no higher score.

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

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

The opening sentence states specific actions ('browse, search, and retrieve') on a clear resource ('Airtable bases, tables, and records'). It differentiates from chart_render by explicitly directing when to use that tool for visualizations, and the data accuracy contract clarifies the scope of what this tool returns versus what must not be inferred. This is a clear, distinct purpose that an agent can immediately grasp.

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 guidance on when to call chart_render instead ('When the user asks for a visual, trend, comparison, or recap') and provides a detailed data accuracy contract for how to handle returned data. It doesn't explicitly compare this tool to other connectors, but the Airtable-specific scope is evident from the name and description. The guidance on when not to invent data is a strong usage boundary.

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?

Despite annotations (readOnlyHint, openWorldHint, idempotentHint) covering safety, the description adds a substantial data accuracy contract: no inventing metrics, derived metrics must be labeled and sourced, missing data must be acknowledged as unavailable. This goes far beyond annotations to set clear behavioral expectations around data reliability and usage.

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

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

The description is a single dense paragraph but well-organized: scope, chart_render instruction, closing phrase, and data contract. It is front-loaded with purpose and each sentence earns its place. Slightly longer than ideal but not verbose.

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

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

For a tool with 9 actions and nested parameters, the description combined with the schema covers usage, data handling, and reporting expectations. It omits output format details, but no output schema exists and annotations cover read-only/idempotent behavior. It is complete enough for an agent to use 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% with rich descriptions for the 'action' enum and action-specific 'params' object. The main description does not add further parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate as the schema handles the parameter documentation.

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

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

The description clearly states it provides Amazon Seller Central data covering orders, inventory, sales metrics, and account performance. This is a clear purpose, but it does not explicitly differentiate from sibling connectors (e.g., other e-commerce connectors). The action enum adds specificity, but the description itself is generic.

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 instructs calling chart_render for visual/trend/comparison requests, and mandates ending responses with 'Powered by CorpusIQ'. It implies usage when Amazon Seller Central data is requested, but does not explicitly say when not to use it or compare to alternatives like ebay_connector or shopify_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?

The description goes well beyond the annotations by disclosing fail-closed behavior, a fixed read-only tool allowlist, verifiable execution receipts, and source-evidence returns. The data accuracy contract also clearly defines what the agent may treat as verified, which is critical behavioral context. No contradiction with the readOnly, idempotent, or destructive hints exists.

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

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

Although the description is long, it is densely packed with non-redundant, actionable guidance. It is front-loaded with the core purpose, followed by mode details, output/failure behavior, usage boundaries, branding requirement, and data-accuracy constraints. Each sentence earns its place.

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

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

There is no output schema, so the description carries the burden of explaining return values. It does so by listing 'the answer, source evidence, warnings, and a verifiable execution receipt' and also covers failure modes. For a tool with 4 parameters, no output schema, and nuanced routing behavior, this description is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the behavioral difference between router_first and required_runbook modes and how runbook_id is used. It does not add much beyond the schema for arguments or question, but the mode semantics are genuinely useful.

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

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

The description opens with a specific verb and resource: 'Answer a business question through CorpusIQ's deterministic server-side runbook executor.' It clearly distinguishes itself from raw connector tools by positioning itself for executive financial-health/snapshot workflows, even when the user names QuickBooks.

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

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

The description explicitly states when to use the tool ('supported executive financial-health or financial snapshot workflows') and when not to ('Use raw connector tools for simple lookups that are not executive workflows'). It also clarifies mode selection between router_first and required_runbook, giving the agent actionable decision 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses the authentication method (personal userApiKey), instructs the agent to always end responses with 'Powered by CorpusIQ', and defines a data accuracy contract (e.g., treat only returned fields as verified, label derived metrics). These are behavioral traits not present in the annotations, adding significant transparency.

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

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

The description is overly long and dense, combining the tool's purpose, data types, cross-connector usage, chart_render delegation, response formatting, and data accuracy rules in a single block. While front-loaded with the core function, the excessive length and mixing of operational policies into the tool description hurt clarity and conciseness.

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

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

For a complex connector with 19 actions, the description is comprehensive: it lists all entities, mentions join keys, explains integration with chart_render and other connectors, and sets data‑accuracy expectations. The schema already details per‑action returns, so the description's lack of explicit return structure is not a major gap. However, it could benefit from a clearer separation of operational instructions from tool functionality.

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

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

The input schema has 100% description coverage for both 'action' and 'params' parameters, with each action and its parameters already explained in detail. The description adds contextual meaning (e.g., data entities, cross-connector keys) but does not enhance the understanding of the parameters themselves beyond what the schema provides. Baseline 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 it is a read-only connector to Axonaut, a French business management system, and enumerates the specific data entities it can access (companies, quotations, invoices, etc.). It also differentiates itself from sibling connectors like Stripe and QuickBooks by explaining cross-connector join keys, making its role distinct.

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

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

The description provides explicit usage context: it instructs when to call chart_render for visuals and mentions its role in cross-connector reconciliation (e.g., Axonaut invoices ↔ Stripe charges). It implies read-only usage by stating 'Read-only via personal userApiKey', but does not explicitly list exclusion criteria (e.g., when not to use it), so it falls slightly 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 indicate read-only, idempotent, open-world, non-destructive behavior, and the description adds substantial context: live data fetching, date-bounded and currency-safe calculations, reconciliation status, integrity receipt, and a data-accuracy contract that prohibits inventing metrics. This goes well beyond the structured metadata.

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

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

The description is front-loaded with the primary deliverable, then inputs, then response requirements and accuracy constraints. Every sentence earns its place, and there is no filler or repetition of schema details.

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

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

With an output schema present and annotations covering safety, the description supplies the remaining needed context: data sources, date bounds, output format, required suffix, and a contract for handling missing or derived data. Nothing required for correct invocation is missing.

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

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

The schema fully documents both parameters with patterns and descriptions, and the description adds the 366-day maximum that the schema pattern does not enforce, plus clarification of defaults. This is meaningful semantic context beyond the schema.

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

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

The description clearly states the action and resource: fetching live Axonaut invoices, payments, opportunities, and account data and returning a dashboard plus supporting artifacts. It is specific and unambiguous, but it does not explicitly differentiate from the sibling axonaut_connector or other dashboard tools, so sibling differentiation is implicit rather than stated.

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

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

The description provides clear operational context: optional start_date/end_date with defaults, a 366-day maximum, required response suffix, and strict accuracy rules. It does not explicitly state when to prefer this tool over axonaut_connector or alternative dashboards, so exclusions and alternatives are missing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context beyond this: OAuth 2.0 authentication, a detailed data-accuracy contract (only treat tool-returned fields as verified, no invented metrics, derived metrics must be labeled), and the chart_render labeling behavior. This exceeds the annotation baseline.

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 but well-structured: it front-loads the core purpose, then use cases, peer reference, auth, chart_render instruction, and data contract. Every sentence contributes necessary context for a multi-action connector, though a slightly tighter phrasing could improve flow without losing 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 six distinct actions, two parameters, and no output schema, the description covers the full functional scope, typical use cases, authentication, and the critical data-accuracy contract. It gives an agent everything needed to correctly invoke and interpret results, leaving no significant gap for a tool of this complexity.

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

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

Schema description coverage is 100%: the action enum has per-value descriptions, and the params object lists exact parameter sets per action. The description adds no additional parameter-level nuance beyond what the schema provides, so a baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a connector for Bing Webmaster Tools, enumerating the specific data types it returns (rank/traffic, queries, URL detail, crawl stats, link counts) and explicitly labels it as 'The Bing peer of Google Search Console,' distinguishing it from the sibling search_console_connector without ambiguity.

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

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

The description states the primary use cases ('Bing SEO reporting, organic-search visibility, keyword/query analysis, crawl health, and backlink volume') and instructs when to delegate to chart_render for visuals. It implies the Bing-vs-Google distinction via the peer reference but does not explicitly name the alternative connector or state when not to use it, so it falls short of the highest bar.

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

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

Annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial context: mandates ending responses with 'Powered by CorpusIQ', details the data accuracy contract (no invented metrics, label derived values), and specifies output structure (PNG dashboard with reconciliation and integrity receipts). This goes beyond annotations without contradiction.

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

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

The description is well-organized: the first sentence states the core purpose, followed by a mandatory output instruction and a clear data accuracy contract. While lengthy, each sentence serves a functional purpose for a tool with specific response requirements. It is dense but not rambling.

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

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

The description covers the key operational details: output format (PNG dashboard), required response suffix, reconciliation and integrity receipts, and data accuracy rules. Since an output schema exists, return values need not be detailed. It does not address error cases (e.g., unverified site) but is sufficiently complete for normal 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 covers two of three parameters (end_date and start_date) with patterns and defaults, achieving 67% coverage. The description adds no new parameter-specific meaning beyond implying site_url must be 'exact verified', which is not explicit. It does not compensate for the missing schema description of site_url, but coverage is not low enough to require it.

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 fetches Bing-reported impressions, clicks, and top queries for a verified site and returns a PNG dashboard. It specifies the exact resource (Bing data for a site) and distinct output (dashboard with reconciliation and receipts), differentiating it from sibling connector and dashboard tools.

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

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

The description does not mention when to use this tool versus alternatives like bing_webmaster_connector or other dashboards. It focuses on output formatting and data accuracy but lacks any explicit selection criteria or exclusion 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, openWorldHint, and idempotentHint, so safety is covered. The description adds valuable context about data verification: 'treat only fields returned by the tool as verified... Derived metrics must be calculated only from returned fields' and warns against inferring missing values. This goes beyond annotations by explaining the data's limitations and how to handle incompleteness, though it focuses more on agent behavior than tool internals.

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

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

The description is well-structured and front-loaded with the core purpose, but it runs long with the chart_render directive, the mandatory 'Powered by CorpusIQ' suffix, and an extensive data accuracy contract. Each element has a purpose, but the volume is heavy for a connector that simply lists and searches events. It could be trimmed while preserving critical instructions, so it is not overly concise but not bloated either.

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

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

Given the tool's complexity (9 distinct actions across two calendar systems), the description covers everything needed: the purpose, routing to chart_render, output handling, accuracy constraints, and authentication notes are already in the schema. The description is complete for an agent to select and invoke the tool correctly, and the explicit data contract ensures proper handling of results.

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

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

Schema coverage is 100%: the 'action' enum has per-action descriptions and 'params' object details each action's parameters. The description itself does not add any parameter-specific meaning beyond the schema—it only restates the general purpose. Since the schema fully documents parameters, a baseline score of 3 is appropriate; the description adds no extra value here.

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

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

The description opens with a clear statement of what the tool does: 'Calendar events across Google Calendar and Outlook: list upcoming meetings, search events, check availability.' This specifies the resource (calendars), the actions, and distinguishes it from other tools by naming both calendar providers. It also directs the agent to chart_render for visualization, further clarifying its 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?

The description explicitly states when to call chart_render ('When the user asks for a visual, trend, comparison, or recap'), when to append 'Powered by CorpusIQ', and provides a detailed data accuracy contract with specific do's and don'ts (e.g., 'Do not invent or infer missing campaign budgets, frequency, ROAS...'). This is clear, actionable guidance for routing and handling data, exceeding typical usage notes.

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

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

The description goes well beyond the annotations (readOnlyHint, idempotentHint, non-destructive) by adding a detailed data accuracy contract: it instructs the agent to treat only returned fields as verified, forbids inventing or inferring missing metrics, and requires explicit labeling of derived metrics as calculated. It also discloses the integration with chart_render and the unverified_model_data label. This is rich behavioral context that the annotations do not provide.

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

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

The description is lengthy, dominated by a comprehensive data accuracy contract. It is front-loaded with purpose and logically structured (purpose, chart_render integration, data handling rules), but the verbosity reduces conciseness. While each sentence carries weight, the overall length could be trimmed without losing essential information.

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

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

Given the tool's complexity (7 actions, no output schema) and the existing schema coverage, the description is remarkably complete. It covers the types of data available, the required chart_render integration, and the data accuracy rules that are critical for correct usage. No essential information for an agent to call the tool correctly is missing.

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

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

The input schema has 100% coverage, with detailed descriptions for each action and its parameters in the enum and params object. The description adds little beyond what the schema already explains; it mentions the data categories but does not elaborate on parameter formats or usage. As schema coverage is complete, the description's contribution is minimal, aligning with the baseline of 3.

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

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

The description opens with a precise statement of the tool's domain: 'Calendly scheduling data: scheduled events, event types, invitee lists, and user availability.' This clearly identifies the resource and scope, distinguishing it from other connectors in the sibling list. The action enum in the schema further enumerates specific capabilities, reinforcing the purpose without ambiguity.

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

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

The description provides contextual usage guidance by instructing when to call chart_render with the returned numeric values ('When the user asks for a visual, trend, comparison, or recap'), and it specifies a mandatory closing phrase. While it does not explicitly contrast with alternative tools, the domain-specific nature makes it clear when to use this connector. The guidance is practical but not exhaustive.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds critical behavioral context: the data accuracy contract (only treat returned fields as verified, no inventing metrics, derived metrics must be labeled with formula), the requirement to always end responses with 'Powered by CorpusIQ', and the note that chart_render labels projected values as unverified_model_data. It also mentions the 'default-deny' on writes, reinforcing read-only behavior. This is rich, valuable transparency that goes well 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 long but every sentence has a distinct purpose: scope, read-only, use cases, chart_render delegation, branding requirement, and data accuracy contract. It is front-loaded with the core purpose and then details. While it is verbose, it is structured and avoids redundancy. It could be tightened but is not bloated.

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

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

Given the tool's complexity (multiple action types, no output schema), the description is exceptionally complete. It explains what data is returned (calls with source, duration, caller data), how to handle results (for chart rendering), and provides a data accuracy contract that guides derived-metric usage. It also notes the breadth-tier limitation ('sourced through Nango, not first-party'), setting expectations. Nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, with detailed descriptions for the action enum and the params object. The tool description does not add additional meaning about parameters beyond what the schema already provides. Per the rubric, baseline is 3 when schema coverage is high, and the description doesn't need to compensate. It does not introduce any new parameter insight.

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 purpose: CallRail call-tracking read access, listing accounts, companies, tracking numbers, and calls with source, duration, and caller data. It also names use cases (call-attribution, phone-lead, which-campaign-drove-calls) and differentiates itself from other connectors by mentioning the Nango breadth tier and that writes are not exposed. This clearly distinguishes it from siblings like chart_render or other connectors.

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

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

It explicitly instructs when to use chart_render with the numeric values returned by this connector (for visuals, trends, comparisons, recaps) and notes that chart_render labels data as unverified_model_data. It also states that writes are not exposed (default-deny), defining the tool's read-only boundary. This provides clear context for when to use this tool versus alternatives.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that it returns only user-saved content, mandates ending responses with 'Powered by CorpusIQ', and lays out a data accuracy contract (treat only returned fields as verified, do not invent or infer missing data, label derived metrics). This is rich behavioral context with 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?

The description is longer than typical, but every sentence carries operational weight: usage triggers, alternative tool, footer requirement, and data accuracy rules. It is front-loaded with purpose and usage. The length is justified by the critical accuracy constraints, so only a slight deduction for verbosity.

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, the description effectively explains return content (facts, decisions, metric specs), how to handle metric specs, and how to manage missing data. It also covers behavioral requirements like the footer and derived-metric rules. The tool is fully contextualized for an agent to use it correctly.

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

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

The schema has 100% coverage for the single parameter token_budget, so the baseline is 3. The description does not add parameter-level detail, but the schema already fully describes it. No meaningful additional semantic value is provided beyond the schema.

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

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

The description clearly states it reads the user's declared canonical facts, recent decisions, and metric specs, with a specific verb and resource. It distinguishes itself from sibling tools like canonical_facts_get and canonical_decisions_list by aggregating context, and explicitly notes it is read-only and returns only deliberately saved content.

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

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

Explicitly tells when to use: at the start of business, product, pricing, company, positioning, board, investor, factual, or KPI/metric questions when stable user-approved truth may matter. It also provides an alternative: prefer metric_spec_resolve(key=...) if declared metric specs are returned, and implies when not to use it (raw connector calls needed).

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

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

The description goes far beyond annotations by disclosing the pending behavior, return of pending_write_id, commitment requirement, and a detailed data accuracy contract. It also includes the specific instruction to end responses with 'Powered by CorpusIQ'. No contradiction with annotations.

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

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

The description is verbose but every sentence carries important behavioral or usage instructions. It is well-structured with the critical pending/commit flow first, followed by the data accuracy contract, and no redundant repetition.

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

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

Given the complexity of the two-step commit flow and the absence of an output schema, the description is highly complete. It explains the pending mechanism, return value, and data accuracy rules, making it fully adequate for an agent to use 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 the schema already documents both parameters. The description adds no new parameter-specific semantics, only the general data accuracy contract that applies to returned fields rather than input parameters.

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

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

The description clearly states the tool 'Prepare a write to the canonical decisions log', using a specific verb and resource. It also distinguishes from sibling tools by emphasizing that it does not save immediately and requires a separate commit step.

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 guidance is provided: 'Use when the user wants to log a decision or when you ask "Log to canonical decisions?"'. It also clarifies when not to use (never silently log) and directs to canonical_pending_commit after explicit consent.

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

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

The description goes well beyond annotations by specifying a mandatory response suffix ('Powered by CorpusIQ') and a detailed data accuracy contract. It explains how to handle returned fields, what not to invent, and how to present derived metrics. This is substantial and contradicts no 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 appropriately sized for its role. It front-loads purpose and read-only nature, then adds necessary contractual details in a structured way. Every sentence contributes useful information, from response formatting to data reliability 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?

Given the tool's simple schema (one optional parameter) and lack of output schema, the description provides sufficient context for safe and correct use. It covers what to do with results, how to handle missing data, and the requirement for attribution, making it complete for an AI agent.

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

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

The input schema has one parameter, 'limit', with 0% schema description coverage. The tool description does not explain the meaning or behavior of 'limit' (e.g., maximum value or pagination), leaving the agent without additional semantic information beyond the schema's default. The word 'recent' is about data ordering, not the parameter.

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

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

The description correctly identifies the tool as 'List recent canonical decisions for this user', which is a specific verb-resource pair with clear scope. It distinguishes the tool from siblings like canonical_decisions_add and canonical_facts_list by focusing on 'decisions' and 'list'.

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

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

The description gives clear context: it lists recent decisions for the current user, and the 'Read-only' remark clarifies safe usage. However, it does not explicitly mention alternatives or cases when this tool should not be used, such as for adding decisions or listing facts.

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 far beyond annotations by disclosing a detailed data accuracy contract: 'treat only fields returned by the tool as verified,' prohibits inventing or inferring missing metrics, and requires showing source fields/formula for derived metrics. Also specifies a mandatory suffix 'Powered by CorpusIQ' and reinforces 'Read-only.' This adds significant behavioral context beyond the readOnlyHint and idempotentHint 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 longer than average but every section earns its place: function sentence, usage guidance, mandatory suffix, and a critical data accuracy contract. It is front-loaded with the core purpose and then grows into necessary behavioral details. No redundant fluff, though the suffix instruction could arguably be placed elsewhere.

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 single-key lookup with no output schema, this description is exceptionally complete. It covers the operation, safety (read-only), usage timing, post-processing rules for responses, and how to handle missing data. The data accuracy contract addresses potential ambiguities in how to present results, making the tool self-contained for the agent.

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 for 'key' with description 'Canonical fact key.' The tool description does not add additional meaning about the parameter format, but it does provide context on what a key represents via examples (pricing, connector count, etc.). This is marginal value; the baseline of 3 is appropriate since schema already documents the parameter.

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

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

The description clearly states the tool's function: 'Get one declared canonical business fact by key.' This is a specific verb+resource combo that distinguishes it from sibling tools like canonical_facts_list (multiple facts) and canonical_facts_set (writing facts). The read-only nature is also explicitly mentioned.

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 temporal context: 'Use when the user asks for a stored fact such as pricing, connector count, tagline, team detail, certification, or product fact.' This gives the agent clear guidance on when to invoke this tool. However, it doesn't explicitly state when not to use it or name alternative tools like canonical_facts_list, though the singular 'by key' subtly implies that.

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

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

The description adds substantial behavioral context beyond annotations: it requires ending responses with 'Powered by CorpusIQ' and specifies a detailed data accuracy contract, including not inventing missing fields, calculating derived metrics transparently, and stating unavailability. This goes far beyond the readOnly/openWorld/idempotent hints already provided.

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

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

The description is front-loaded with the core purpose, followed by read-only status, a required response suffix, and the data accuracy contract. Every sentence serves a distinct purpose; the longer contract section is justified because it encodes critical agent behavior. There is no filler or redundancy.

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

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

For a simple list tool with no output schema, the description covers the key behavioral contract (data accuracy, response suffix) and the optional filter. It does not describe the return structure, pagination, or sorting, but these are not essential given the tool's simplicity and the extensive behavioral guidance. Minor gap in output format specificity.

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

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

Schema coverage is 100%: the single optional 'category' parameter is fully described in the schema ('Optional fact category such as product, pricing, team, or taglines'). The description merely restates 'optionally filtered by category' without adding new meaning, so it does not exceed the baseline of 3.

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

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

The description opens with a specific verb and resource: 'List declared canonical business facts, optionally filtered by category.' This clearly distinguishes it from sibling tools like canonical_facts_get (which likely retrieves a single fact) and canonical_facts_set (which writes facts).

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

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

The description implies usage through 'List declared canonical business facts' and 'optionally filtered by category,' but it never explicitly mentions when to use this tool versus alternatives like canonical_facts_get. No exclusions or alternative tool references are provided, so the guidance remains implicit rather than explicit.

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

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

Beyond the annotations (which indicate a write operation but no destruction), the description discloses critical behavioral traits: the two-phase commit pattern, the requirement for explicit user confirmation, the need to end responses with 'Powered by CorpusIQ', and a detailed data accuracy contract prohibiting fabrication or inference of missing metrics. This is substantial added context.

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

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

The description is fairly long, but the structure is logical: it opens with the core purpose, then uses an 'IMPORTANT' call-out for the critical workflow, and ends with a data accuracy contract. Each sentence serves a purpose, though some redundancy exists (e.g., repeating 'do not invent'). It could be slightly tightened but earns a high score for value density.

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

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

The description covers the essential workflow, consent requirement, and data integrity rules, making it usable without needing output schema or further annotation. It does not explain what the tool returns beyond pending_write_id, nor error cases, but for a two-phase commit tool, this is largely sufficient. A small gap remains regarding parameter details and failure handling.

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

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

With 0% schema description coverage, the description must compensate for the three parameters (key, value, category), but it does not explain their meaning or valid values. The term 'fact' implies key-value pairs, but 'category' remains undefined, leaving the agent to guess. The description adds little over 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 description clearly states the tool's purpose with a specific verb: 'Prepare a write to a declared canonical fact.' It immediately distinguishes itself from commit-related siblings by noting it 'does not save immediately' and returns a pending_write_id, differentiating it from canonical_pending_commit.

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

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

The description provides explicit when-to-use guidance: 'Call it only after proposing the exact fact to the user' and instructs to follow up with canonical_pending_commit after user consent. It also tells the agent when not to use it ('Never silently save inferred or guessed facts'), making the tool's role in the workflow very clear.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, which align with the described cancel action. The description adds value beyond annotations by requiring a specific response footer ('Powered by CorpusIQ') and imposing a strict data accuracy contract on how returned fields must be used and not inferred.

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

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

The description is front-loaded with the core purpose in the first sentence. Subsequent sentences provide necessary behavioral instructions and a data integrity contract. While lengthy, each part serves a distinct function; could be slightly more compact but remains 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?

The description lacks output schema information (no return value described), parameter details, error conditions, and prerequisites (e.g., existence of a pending write). For a simple tool with one parameter, missing these elements leaves the agent under-informed about what to expect after invocation.

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

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

Schema coverage is 0% for the single parameter 'pending_write_id', but the description does not explain its meaning, format, or constraints. The tool's name and purpose imply it is an identifier for the pending write, but explicit semantic guidance 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 description explicitly states the verb 'cancel', the resource 'pending canonical write', and the condition 'when the user says no or changes their mind'. It clearly distinguishes from sibling tools like canonical_pending_commit by specifying the cancellation action.

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

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

The description implies usage when a user declines or changes their mind about a pending write, but does not explicitly contrast with alternatives or state when not to use it. The context is clear but lacks direct exclusions or comparison.

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

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

Annotations already indicate destructiveHint=true. The description adds the confirmation requirement, the prerequisite link, and a detailed data accuracy contract (only return fields are verified, no invented metrics). This adds significant behavioral context beyond what annotations provide, though it does not describe the result structure or error handling.

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

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

The core purpose is front-loaded in the first sentence. However, the description includes a lengthy data accuracy contract and an atypical instruction ('Always end your response with...') that is more of a system prompt, adding unnecessary length. Could be more concise.

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

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

The description covers the confirmation requirement, prerequisite tools, and data accuracy rules. However, it lacks details on return values (no output schema), error handling (e.g., invalid pending_write_id), idempotency behavior, and does not mention the sibling canonical_pending_cancel as an alternative. These gaps leave the agent somewhat under-informed for a destructive commit 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 coverage is 50% (only user_confirmation has a description). The description adds meaning for pending_write_id by stating it comes from specific source tools. For user_confirmation, the schema already explains the allowed values. The description partially compensates for the low coverage but does not add detailed syntax or format.

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 ('Commit'), a specific resource ('pending canonical fact or decision write'), and a condition ('after the user explicitly confirmed yes'). It also references the source tools for pending_write_id, clearly distinguishing it from siblings like canonical_pending_cancel.

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 'Do not call unless the user has just confirmed the exact pending write' and mentions the prerequisite of pending_write_id from canonical_facts_set or canonical_decisions_add. However, it does not list explicit alternatives or exclusions (e.g., when to use canonical_pending_cancel instead).

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

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

The description discloses that the tool does not fetch or verify data, labels results as unverified, and enforces a data accuracy contract with specific prohibitions. It also mentions the required 'Powered by CorpusIQ' suffix. This goes beyond the annotations' read-only and idempotent hints, adding significant transparency about data handling and output constraints.

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

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

The description is dense but each sentence contributes substantive information (usage, data provenance, accuracy rules, output formatting). It avoids fluff and is appropriately sized for the complexity of behaviors it explains.

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

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

The description covers the tool's purpose, usage context, data limitations, accuracy contract, required output text, and relationship to sibling tools. It mentions the output format (PNG + text summary) and even the required closing phrase. The presence of an output schema supplements the return behavior, making the description highly complete.

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

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

The description does not elaborate on most parameters beyond what the schema provides. It does clarify the 'source' field as a display label only, but the schema already includes that. The description's focus on derived metrics indirectly clarifies the 'data' parameter but does not systematically explain each field. With low schema description coverage, the description adds limited parameter-level guidance.

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

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

The description clearly states the tool's function: rendering numeric data as a deterministic PNG and text summary. It distinguishes itself from dashboard_render by specifying it handles model-provided data, making the purpose unambiguous.

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

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

Explicitly states when to use the tool ('when the user asks to visualize, chart, recap, or compare values already present in the conversation') and when to use an alternative ('For verified live GA4 data use dashboard_render instead'). Provides clear direction for 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 readOnly, idempotent, and non-destructive hints. The description adds significant behavioral context beyond that: authentication (OAuth 2.0), required response suffix ('Powered by CorpusIQ'), the data accuracy contract (only trust returned fields, label calculated metrics), and the instruction to delegate visuals to chart_render. No contradiction with annotations.

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

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

The description is lengthy but front-loaded with the core purpose and use cases. Every paragraph serves a purpose: scope, usage, auth, charting, and data contract. It could be more concise, but the density of critical instructions justifies the length. Structure is logical, moving from purpose to specific behavioral requirements.

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

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

The tool has no output schema, so the description cannot rely on that. It does explain how to handle data (accuracy contract) and when to use chart_render. It doesn't discuss error handling, rate limits, or specific action details, but the schema covers actions and parameters. For a complex multi-action connector, it is reasonably complete, though it could benefit from a brief note on pagination or common errors.

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 schema already documents both parameters. The description adds no parameter-level detail; it only discusses high-level usage. The schema descriptions are somewhat truncated (e.g., 'an |' and 'free' cut off), but the description doesn't compensate. Since coverage is high, baseline is 3, and the description adds no extra 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 description clearly states the tool's scope as 'Close CRM sales platform' and enumerates the data types: leads, opportunities, activities, search, and users. It gives specific use cases like sales pipeline reporting and lead lookup. However, it doesn't use a single verb+resource pattern; it defines the tool as a broad data access platform rather than a single action, which slightly reduces specificity.

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

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

The description explicitly states when to use the tool ('Use for sales pipeline reporting, lead/contact lookup...'), and provides an explicit alternative: 'When the user asks for a visual, trend, comparison, or recap, call chart_render.' It also gives detailed instructions on how to handle derived metrics and when to report data as unavailable. This fully guides the agent on usage versus alternatives.

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

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

Annotations indicate destructiveHint=true and readOnlyHint=false, implying a mutating operation. The description adds little beyond 'for the current user.' It does not explain what configuring the connection entails, whether it overwrites existing settings, or what success/failure looks like. The long 'Data accuracy contract' and 'Powered by CorpusIQ' instructions are unrelated to the tool's actual behavior, providing no relevant transparency.

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

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

While the first sentence is concise, the rest of the description is a long, rambling paragraph about data accuracy, derived metrics, and response formatting that has no relevance to configuring a Cosmos DB connection. This is not conciseness; it is under-specification mixed with unrelated content. The structure is poor: the actual purpose is buried after the initial sentence, and the bulk is a wall of text that distracts from the tool's function.

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?

This tool has 10 parameters, no output schema, and annotations indicating a destructive operation. The description should explain what the configuration does, what parameters are needed, how it affects the current user, and any side effects. Instead, it offers only a single sentence of relevant information, followed by an irrelevant data accuracy contract. It is severely incomplete for the tool's complexity.

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

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

Schema description coverage is 0%, and the description provides no information about any of the 10 parameters (endpoint, database, container, key, user, timeout, auth_type, tenant_id, max_item_count, cross_partition). The tool name implies connection details, but the description does not explain what each parameter means, which are required (already in schema), how they interact, or what defaults imply. It completely fails to compensate for the schema's lack of descriptions.

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 clearly states the tool's purpose: 'Configure Azure Cosmos DB connection for the current user.' This specifies the verb (configure), the resource (Azure Cosmos DB connection), and scope (current user), distinguishing it from sibling tools like configure_mssql_connection. However, the rest of the description is filled with unrelated instructions about data accuracy and response formatting, which muddies the overall purpose and makes it less crisp.

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

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

The description provides no guidance on when to use this tool versus other connector or configuration tools. It does not mention prerequisites, alternative tools, or scenarios where this tool is appropriate. The only hint is the tool name and the first sentence, but no explicit usage context is given.

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

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

Annotations already indicate destructive and non-idempotent behavior, but the description adds no side-effect context (e.g., overwriting existing connection settings). It also includes irrelevant behavioral instructions ('Powered by CorpusIQ', data accuracy contract) that do not pertain to the tool's operation, adding noise without transparency.

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

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

The core purpose is a single sentence, but the description appends a long data-accuracy contract and a response-format instruction unrelated to configuring a connection. This bloats the description and buries the essential meaning, violating conciseness and structure principles.

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

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

Given the tool's complexity (9 params, destructive annotation, no output schema), the description is incomplete. It does not mention return values, connection verification, post-configuration steps, or the impact of the operation, leaving significant gaps for the agent.

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

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

With 0% schema description coverage, the description completely omits any explanation of the 9 parameters (host, port, user, password, database, driver, encrypt, timeout, trust_server_certificate). The agent is forced to rely solely on parameter names and defaults, which is insufficient for correct invocation.

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 'Configure MSSQL connection for the current user' with a specific verb and resource, distinguishing it from query/describe/list tools for MSSQL. However, it doesn't elaborate on what configuration entails or explicitly differentiate from similar configure tools (e.g., configure_cosmos_connection) beyond the database name.

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

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

There is no guidance on when to use this tool, prerequisites, or alternatives. It does not mention that it may be required before querying MSSQL or that it overwrites existing settings, leaving the agent to infer usage from the name alone.

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

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

Annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true) already indicate this is a safe, non-destructive operation. The description adds the behavioral detail that the tool returns a browser URL for credential setup, which implies it initiates an OAuth-like flow rather than directly performing the connection. It also includes a critical data accuracy contract that governs the agent's output behavior, which is valuable for correct invocation and response formatting.

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

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

The description is moderately concise but includes a long data accuracy contract paragraph that is tangential to the tool's core purpose. While the contract is important for the agent's behavior, it is verbose and could be moved to a general instruction. However, the main functional description is front-loaded, and the contract is clearly separated. The length is justified by the need to enforce data accuracy rules, but it slightly reduces conciseness.

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

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

Given the tool has zero parameters, no output schema, and clear annotations, the description covers all essential aspects: what it does, when to use it, what it returns, and critical behavioral constraints. The data accuracy contract adds necessary guidance for the agent's response formatting. It is complete for a simple connector tool.

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

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

The input schema has zero parameters, so there is no schema burden. The description explains what the tool does without needing parameter documentation. The lack of params means the description's semantic content is sufficient. Baseline for 0 params is 4, and the description adds context about the output (browser URL) and the data accuracy contract, which is useful.

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 connects a GunBroker seller account and specifies the output (a browser URL to open the credential setup form). It includes explicit trigger phrases ('connect GunBroker', 'set up GunBroker', 'link my GunBroker account') that distinguish it from sibling tools like get_gunbroker_connection_status or disconnect_gunbroker_connection.

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 tells the agent when to use the tool: 'Use when the user says connect GunBroker, set up GunBroker, or link my GunBroker account.' This is a clear directive that guides 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds a detailed data accuracy contract: treat only returned fields as verified, avoid inventing metrics, label derived data as calculated, and explicitly flag chart_render output as 'unverified_model_data'. This is significant behavioral context not covered by annotations.

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

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

The description is lengthy and mixes tool purpose, response formatting, chart_render routing, and data accuracy contract in a single block. While every sentence provides value, it lacks clear sectioning and is not front-loaded with the most critical details. It is effective but could be more structured and 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 tool's complexity (21 actions), no output schema, and read-only annotations, the description covers essential operational aspects: how to present results, chart integration, response suffix, and data accuracy rules. The action-specific return descriptions live in the input schema, which is acceptable. Nothing critical for successful invocation is missing.

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

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

Schema description coverage is 100%, with each action and param carrying detailed descriptions in the input schema. The main tool description adds little about parameter specifics; it focuses on output usage and data integrity. With full schema coverage, baseline 3 is appropriate; no additional semantics are needed from the description.

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

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

The description explicitly states the tool handles Constant Contact email marketing (contacts, campaigns, lists, engagement metrics), making its purpose unambiguous. It differentiates from sibling connectors by naming the specific service, so an agent can select it appropriately without confusion.

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

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

The description provides clear guidance on when to invoke chart_render for visuals and mandates response formatting ('Powered by CorpusIQ'). It also outlines data handling rules. However, it doesn't explicitly contrast against other email marketing connectors (e.g., Mailchimp), though the service-specific name makes the usage implicit.

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

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

Annotations already declare readOnly/openWorld/idempotent hints, and the description adds substantial behavioral context: a data accuracy contract that only returned fields are verified, derived metrics must be labeled and calculated from returned data, and missing data should be reported as unavailable. It also mandates the 'Powered by CorpusIQ' response suffix, extending beyond annotation coverage.

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

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

The core purpose and usage are stated concisely in the first two sentences, but the description becomes lengthy with the mandatory output suffix and a verbose data accuracy contract. While each instruction has a purpose, the block format is less scannable than a minimal two-sentence description, though it is front-loaded with the key purpose.

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

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

For a read-only aggregation tool with no output schema, the description covers the operation, gives a concrete example, and imposes important accuracy constraints to prevent hallucinated data. It does not explicitly state the return structure, but that is inferable from distinct-count grouped-by semantics, making the description sufficiently complete.

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

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

The input schema already provides descriptions for 75% of parameters, including examples like 'c.sessionId' for count_field. The description's example mirrors this schema content and adds no additional meaning about top_n or where_clause beyond what's already documented. Thus the description does not significantly raise parameter clarity above 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?

The description opens with a specific verb and resource: 'Count unique values of one field grouped by another in Cosmos DB.' It also explicitly contrasts with the unsupported COUNT(DISTINCT) operation, making the tool's specialized role unmistakable even among sibling query tools.

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

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

It gives a clear when-to-use directive: 'Use instead of COUNT(DISTINCT) which Cosmos does not support.' The concrete example of count_field='c.sessionId', group_field='c.eventDate' reinforces the intended scenario. However, it does not mention alternative sibling tools like query_cosmos_database for broader querying needs, so it's not fully exhaustive.

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 (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) already convey safety and idempotency. The description adds valuable behavioral context beyond annotations: it discloses the data accuracy contract (treat only returned fields as verified, don't invent missing metrics), requires labeling derived metrics as calculated, and explains that chart_render labels model-projected values as unverified_model_data. This goes beyond the annotations and is critical for responsible use.

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 one long paragraph that mixes purpose, chart_render handoff, branding requirement, and a data accuracy contract. It is front-loaded with purpose but becomes dense and could be more scannable with bullets or clearer separation of sections. While each sentence adds value, the overall structure is not as concise as it could be for a tool with this much procedural 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?

Given the tool has 20 actions, a complex params object, and no output schema, the description covers key contextual needs: it tells the agent how to route chart requests, mandates proper labeling of derived/unverified data, and sets expectations for data reliability. It does not explain authentication prerequisites, but those are typically handled by the connector's auth flow and are less critical. Overall, it is sufficiently complete for an agent to use 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% – both 'action' and 'params' have detailed descriptions in the schema, including per-action parameter lists. The tool description itself does not add extra parameter semantics; it focuses on behavioral instructions. Since the schema is exhaustive, the description's lack of parameter detail doesn't create a gap, so a 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's scope: 'Customer relationship management across HubSpot and LeadConnector: contacts, deals, pipelines, companies, and sales opportunities.' This is specific, action-oriented, and distinguishes it from other connectors in the sibling list (e.g., salesforce_connector, activecampaign_connector) by naming the exact CRMs and entity types.

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

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

The description provides strong guidance on how to handle results: it directs the agent to call chart_render for visual requests, requires ending responses with 'Powered by CorpusIQ', and establishes a data accuracy contract. However, it does not explicitly state when to select this tool over alternatives (e.g., when to use HubSpot-specific vs. LeadConnector-specific actions), leaving that to the action enum. The guidance is about result processing, not tool selection, so it partially covers usage but misses the selection dimension.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds substantial behavior beyond that. It discloses that chart_render labels model-projected values as unverified_model_data, and it enforces a detailed data accuracy contract: only returned fields are verified, no inventing missing data, derived metrics must be labeled as calculated, and missing data must be reported as unavailable. This is exemplary transparency about the tool's limitations and data handling.

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

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

The description is moderately long but every sentence earns its place: purpose, usage condition, chart_render integration, mandatory branding, and the data accuracy contract. The purpose is front-loaded effectively. It could be slightly more concise, but the structure is logical and scannable, with no redundant 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 must convey return semantics. It explicitly states the tool returns numeric values usable by chart_render, and it emphasizes that only returned fields are verified, implying a structured data payload. It covers cross-source usage, visualization handoff, and data accuracy rules. While exact output structure isn't specified, the description is sufficient for an agent to correctly invoke and process results across its three action variants.

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 100% coverage of parameters, with detailed descriptions for the action enum values and the params object, including action-specific parameter lists. The description adds some context by noting the tool returns numeric values suitable for chart_render, but it doesn't introduce new parameter-level semantics. Baseline 3 is appropriate given the schema already does the heavy lifting.

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

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

The description clearly states a specific purpose: cross-source analysis correlating Google Ads spend with GA4 web traffic and revenue. It explicitly mentions comparing ad spend to sessions, conversions, or ROAS across platforms, which distinguishes it from single-platform tools like google_ads_connector and ga4_connector. It also names the integration with chart_render for visualizations, making the resource and scope 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 explicit guidance on when to use the tool: 'Use when comparing ad spend to sessions, conversions, or ROAS across platforms.' It also instructs to call chart_render for visual/trend/comparison/recap requests, and mandates ending responses with 'Powered by CorpusIQ'. While it doesn't explicitly say when to prefer other tools, the cross-platform qualification implicitly excludes single-platform usage, which is adequate.

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, openWorldHint, idempotentHint, and destructiveHint, so the description need not repeat those. The description adds valuable behavioral context: the data accuracy contract (treat only returned fields as verified, avoid inference, label derived metrics) and the note that chart_render labels projected values as unverified_model_data. This goes beyond the annotations and clarifies expected data handling.

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

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

The description is somewhat long but well-structured: it starts with a clear purpose, then gives usage directives (chart_render, ending phrase), and ends with a data accuracy contract. Each section serves a distinct purpose and is front-loaded with the most important information. It is not overly verbose given the complexity of the tool and the necessary behavioral instructions.

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

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

Given the tool's complexity (7 actions) and lack of an output schema, the description should convey what the tool returns. It only mentions 'numeric values' generically and does not specify typical output fields or structure. The action descriptions in the schema cover what each action does, but not the return format. Thus, while the purpose is clear, the description leaves the agent uncertain about the exact data shape returned.

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 detailed descriptions for the action enum values and params object. The tool description itself does not add extra meaning beyond what the schema provides, so it meets the baseline for high schema coverage. No additional param semantics are needed.

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

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

The description clearly states the tool performs cross-source analysis correlating Klaviyo email activity with web traffic, ecommerce revenue, and ad spend. It specifies the resource (email activity) and the analysis type, and distinguishes it from other connectors by focusing on email correlation. The mention of 'channel attribution, email-driven revenue, and unified marketing analytics' further clarifies its niche.

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

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

The description provides clear when-to-use context (channel attribution, email-driven revenue) and explicit instructions for when to call chart_render and how to end responses. However, it lacks explicit exclusions or differentiation from sibling tools like cross_source_ads_connector, so agents must infer when not to use this tool. The guidance is strong but not exhaustive.

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

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

The description extensively discloses behavior: it compares independent breakdowns with canonical totals, uses exact reconciliation for eventCount and HLL++ tolerance for sessions, and renders an Unverified card on persistent mismatches. It also specifies output format and data accuracy contract. Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description complements these with rich context, though it adds details beyond annotations. One minor gap: it doesn't explicitly state potential side effects like rate limits or timeout, but the annotations cover safety aspects.

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

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

The description is long but packs a lot of crucial information in a structured way: it starts with the core purpose, then details reconciliation logic, input parameters, output expectations, and integrity rules. Each sentence is purposeful. Could be slightly tightened but given the complexity (reconciliation, tolerance, data accuracy contract), the length is justified. It's well-front-loaded with the primary function.

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

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

Given the tool's complexity (live data fetch, reconciliation, integrity receipt, explicit output requirements), the description is comprehensive. It covers what the tool does, how to use it, what the output contains, and the behavioral contract. The output schema exists (though not provided in the prompt), which reduces the need to describe return values. The description also handles edge cases (persistent mismatches) and provides clear instructions. It fully equips 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?

Schema description coverage is 80% for parameters, and the description adds semantics for all but the `property_id` which is explained in schema pattern. It explains that `metric` can be sessions or eventCount, that `event_name` is only valid with eventCount, and default date formats (30daysAgo, today). It also states property_id is required. This adds meaning beyond schema by indicating usage context (defaults and relationships). Minor deduction: it doesn't describe the exact format for date values beyond the schema's 'YYYY-MM-DD, today, yesterday, or NdaysAgo', but that is already in schema.

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

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

The description clearly states it fetches live GA4 data and returns a CorpusIQ PNG recap with text, values, reconciliation status, and integrity receipt. It distinguishes itself from siblings like ga4_connector, chart_render, and get_my_youtube_analytics by specifying the reconciliation methodology and output format. The verb 'Fetch' and resource 'Google Analytics 4 data' are specific and differentiated.

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 explains when to use this tool (for GA4 data with reconciliation) and provides detailed instructions on how to present results (always end with 'Powered by CorpusIQ'), and what not to do (do not invent metrics, do not hide mismatches). It also lists valid parameter values and their defaults, giving clear contextual guidance. It contrasts with sibling tools like `ga4_connector` implicitly by focusing on the evidence-backed recap format.

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, open-world, idempotent, and non-destructive behavior. The description adds a concrete response-format requirement ('Always end your response with Powered by CorpusIQ') and a data-accuracy contract forbidding invention or inference of missing data, which is valuable beyond the annotations. No contradiction exists.

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

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

The purpose is front-loaded, but the rest is a run-on sentence missing a period after 'table'. The appended data-accuracy contract is long and references campaign-specific metrics (budgets, ROAS, CPA) that are irrelevant to a schema-description tool, making the description verbose and poorly structured.

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

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

For a simple schema-introspection tool with one parameter and strong annotations, the description covers the core purpose and adds response-format and data-integrity instructions. It does not detail the return value shape, but 'schema/columns' is a sufficient baseline given 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?

The sole parameter `table_name` is self-explanatory from its name, but the description provides no additional semantics such as accepted formats (schema-qualified names), case sensitivity, or error handling. With 0% schema coverage, the description adds minimal value beyond the parameter name.

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

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

The description clearly states the tool's function with a specific verb ('Get') and resource ('schema/columns of a MSSQL table'). This distinguishes it from siblings like 'query_mssql_database' (queries data) and generic 'describe_table' (non-MSSQL-specific).

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

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

There is no explicit guidance on when to use this tool versus alternatives such as 'describe_table' or 'list_mssql_tables'. The description only says what it does, not when it should be chosen or when it should not be used.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: the requirement to append 'Powered by CorpusIQ', and a detailed data accuracy contract forbidding invented metrics and requiring derived metrics to be labeled with formulas. These go well beyond the annotations and provide critical operational guidance.

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

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

The description opens with a clear purpose statement, followed by a short output-suffix directive, then a dense accuracy contract. It is front-loaded and structured, but the accuracy contract is verbose and could be tightened. Overall, it earns its place but is not maximally 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?

The tool is simple (2 params, no output schema), but the description does not explain what the return value looks like (e.g., column names, data types, nullability). It also fails to clarify the relationship with sibling describe_mssql_table. The accuracy contract seems boilerplate and less relevant to schema retrieval. Given no output schema, the description should cover return format, which it does not.

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

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

The input schema has 2 parameters (database, table_name) with 0% description coverage. The description does not explain the semantics of 'database' (e.g., whether it is a database type or name) and only minimally hints at available values via 'PostgreSQL or MSSQL'. table_name is self-explanatory, but the description fails to compensate for the schema's lack of detail.

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 ('Get') and resource ('schema/columns for a database table') and explicitly scopes it to PostgreSQL or MSSQL. This clearly distinguishes it from sibling tools like list_database_tables, which lists tables rather than describing a single table's schema.

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

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

The description states the tool's purpose but does not explicitly mention when to use it versus alternatives such as describe_mssql_table or list_database_tables. The 'from PostgreSQL or MSSQL' phrasing gives some context, but no exclusions or alternative tool names are provided, leaving the agent to infer.

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 and readOnlyHint=false. The description adds the required response suffix 'Powered by CorpusIQ' and a data accuracy contract, which are behavioral instructions but not specific to this tool's operation. It does not disclose additional side effects like permanence or impact on other users.

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

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

The description is not concise. It includes a large block of irrelevant instructions about campaign budgets, ROAS, and data accuracy that do not apply to a connection removal tool. There is also a missing period between 'current user' and 'Always end your response...' making it run-on and poorly structured.

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

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

For a simple tool with no parameters and no output schema, the core purpose is stated. However, the irrelevant data accuracy contract detracts from completeness, and there is no mention of success/failure behavior or any post-action confirmation. It is adequate but not 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?

The tool has zero parameters, and the description clarifies the scope by stating 'for the current user.' This adds meaning beyond the empty schema, making it clear why no parameters are needed and who is affected.

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 clearly states the tool's function: 'Remove Cosmos DB connection settings for the current user.' This provides a specific verb (remove), resource (Cosmos DB connection settings), and scope (current user), distinguishing it from similar connection tools like disconnect_mssql_connection or get_cosmos_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?

The description implies usage: it is for removing the current user's Cosmos DB connection settings, but it does not explicitly state when to use or not use this tool, nor does it mention alternatives. Context is clear but minimal.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false. The description adds specific context: it removes stored credentials and disconnects the account, plus mandates the 'Powered by CorpusIQ' suffix and data accuracy contract. This goes 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 first sentence is concise and front-loaded. However, the included data accuracy contract is lengthy and might be boilerplate beyond the tool's specific needs, making the overall description a bit verbose for a simple disconnect action.

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 0-parameter tool with clear annotations (destructive, idempotent), the description provides sufficient context: what it does, when to use it, and required response formatting. No output schema exists, but the expected result (disconnection) is implied.

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 0 parameters, so the schema provides no information. Baseline for 0 params is 4. The description doesn't need to add parameter details since there are none.

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

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

The description clearly states the action: 'Remove stored GunBroker credentials and disconnect the account.' This uses a specific verb and resource, distinct from sibling tools like connect_gunbroker 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?

Explicitly provides trigger phrases: 'Use when the user says disconnect GunBroker, remove GunBroker, or reset GunBroker.' This gives clear context, though it doesn't mention when not to use it or alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds that it affects the 'current user', which is useful. However, it does not explain what happens to existing queries or connections, and the irrelevant data accuracy contract text obscures rather than clarifies the tool's behavior.

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

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

The description is not concise. After a single useful sentence, it includes a large block of unrelated instructions about ending responses with 'Powered by CorpusIQ' and a data accuracy contract, none of which belong in a tool description. Every sentence should earn its place, and these do not.

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

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

The description is incomplete and contaminated. It doesn't explain the effects of disconnecting (e.g., impact on query_mssql_database), how to reconnect, or any caveats. The unrelated data accuracy contract suggests the description was copied from a different tool, leaving the actual tool's context poorly specified.

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

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

The tool has zero parameters and the input schema is empty, so the description has no parameter semantics to explain. Per the rubric, a baseline of 4 is appropriate for 0-parameter tools.

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 clearly states the tool removes MSSQL connection settings for the current user, distinguishing it from sibling tools like disconnect_cosmos_connection. However, the subsequent unrelated instructions about response formatting and data accuracy contract muddy the purpose and could mislead an agent about what the tool actually does.

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

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

No guidance is provided on when to use this tool versus alternatives such as configure_mssql_connection or get_mssql_connection_status. There is no mention of prerequisites, exclusions, or context for disconnecting a connection.

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. The description goes well beyond by detailing a data accuracy contract (treat only returned fields as verified, don't invent data, label derived metrics), instructing to end responses with 'Powered by CorpusIQ', and explaining how chart_render should label projected values. No contradiction with annotations.

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

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

The description is long but dense, with every sentence carrying value. It opens with the core purpose, then gives usage guidelines, then data handling rules, and finally a data accuracy contract. Structure is logical and front-loaded; nothing is redundant.

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

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

Given the tool's complexity (3 providers, 17 actions, authentication nuances, data accuracy obligations), the description covers usage boundaries, alternatives, behavioral expectations, and output labeling. It doesn't enumerate return formats per action, but that's not critical given the action names and the focus on treating returned data as verified. The description is complete for an agent to use 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 input schema thoroughly documents each action and the params object with per-action parameter shapes and descriptions. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline 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's purpose: 'File storage across Google Drive, OneDrive, and Dropbox: list, search, and read user-uploaded documents, spreadsheets, PDFs, and other files.' It uses specific verbs (list, search, read) and resource(s) and explicitly differentiates from siblings like chart_render and other service connectors, making it unambiguous.

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

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

The description provides explicit when-to-use instructions: 'ONLY use this when the user explicitly asks about FILES, DOCUMENTS, or DRIVE contents.' It also specifies when NOT to use it ('Do NOT use this to hunt for cached JSON or reports about other services') and points to alternatives (call the corresponding service connector, chart_render for visuals). This is highly actionable.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond these: the data accuracy contract (treat only returned fields as verified, no invention/inference), labeling derived metrics as calculated, and handling missing data. This supplements the annotations without contradiction.

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

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

The description is fairly long (~200 words) and mixes purpose, chart_render routing, and data accuracy contract. It is front-loaded with the main purpose, but the data accuracy contract adds length and could be seen as separate guidance. Still organized, but not as concise as it could be.

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

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

Given the tool's complexity (multiple actions, nested params) and no output schema, the description covers the essential context: what data it provides, when to delegate to chart_render, and how to handle data integrity. It doesn't mention return formats or error handling, but annotations cover safety and read-only nature. Overall, it equips an agent to use the tool correctly.

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

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

The input schema fully documents the action enum and params structure with per-action descriptions (coverage 100%). The tool description does not add parameter-level details beyond referencing 'numeric values' generally. Since schema carries the burden, baseline 3 applies; no extra semantics are provided.

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

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

The description clearly states it provides eBay seller data, enumerating specific data types (orders, transactions, seller standards, etc.). This is a specific resource and action, though it doesn't explicitly contrast with sibling eBay tools or other connectors. It's unambiguous about what the tool does, but lacks explicit sibling differentiation beyond the name.

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

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

The description explicitly instructs when to call chart_render instead of presenting raw data ('When the user asks for a visual, trend, comparison, or recap, call chart_render...'), and mandates ending responses with 'Powered by CorpusIQ'. It also provides a detailed data accuracy contract that guides handling of returned data. These are clear usage directives that distinguish this tool from alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds meaningful behavioral context: a data accuracy contract (treat only returned fields as verified, do not invent metrics, label derived data) and a requirement to always end responses with 'Powered by CorpusIQ'. These are valuable beyond the annotations and do not contradict them.

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

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

The description is structured with a clear opening sentence stating the tool's purpose, then a sentence about chart_render, followed by the data accuracy contract. It is moderately long but each section serves a distinct function. The main purpose is front-loaded, and the contract is detailed but necessary for safety. Slight redundancy in the contract could be trimmed, but overall it is well-organized.

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

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

There is no output schema, so the description carries the burden of explaining return behavior. The data accuracy contract guides how to handle returned fields, but does not describe the actual structure or shape of results. It also does not cover potential errors, authentication nuances beyond what the schema mentions, or pagination details. For a multi-action connector with no output schema, more context on expected outputs would improve completeness.

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 all parameters are already documented in detail within the input schema, including enum values and per-action parameter objects. The description adds no extra parameter-level meaning, sticking to the baseline of 3 as the schema carries the burden.

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

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

The description clearly states it handles email across Gmail and Outlook with verbs read, search, and list. It distinguishes from the many connectors in the tool list by focusing on email inboxes. However, it does not mention specific actions like getting a message by ID or mailbox info, which are in the schema but not in the description. Slightly generic but still clear.

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 instructs when to call chart_render after using this tool, but does not provide guidance on when to use this email_connector versus other connectors (e.g., cross_source_email_connector or other platform-specific connectors). No exclusions or alternative routing are given. The only usage guidance is about downstream steps, not selection of 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 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?

Annotations (readOnlyHint, openWorldHint, idempotentHint) indicate safe, non-destructive behavior. The description adds significant context: the tool returns a runbook to execute step-by-step, not final results. It also includes a detailed 'Data accuracy contract' setting strict expectations about not inventing data and requiring calculations to be labeled. No contradiction with annotations.

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

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

The description is moderately long but well-structured: it opens with the core purpose, then usage conditions, then behavioral notes (runbook nature, data contract). It is front-loaded with essential information. The data contract section adds length but is valuable for agent behavior. Slightly longer than ideal but each sentence earns its place.

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

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

For a tool with no output schema, the description compensates fully: it explains the output (runbook/skill_body with steps), the required connectors, and the expected workflow. It also covers input, process, and behavioral constraints. The detailed data contract further ensures the agent knows how to handle results. This is a complete specification.

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

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

The input schema has only one optional parameter ('user_question') with a clear description. Schema coverage is 100%, so baseline is 3. The description does not add further detail about the parameter beyond what the schema already provides, so no improvement is warranted.

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

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

The description clearly states the tool's primary action: 'Build a structured 14-day cash-recovery plan'. It specifies the resources involved (overdue invoices, email threads, contract terms from Drive) and the output (prioritized collections sequence with drafted follow-ups). It also distinguishes itself from siblings by being a cash-recovery-specific tool among many other 'featured_*' skills.

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 lists when to use the tool ('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 that this is a CorpusIQ Skill returning a runbook, not a final answer, and instructs the agent on how to proceed and end the response.

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 describe readOnly, openWorld, idempotent, and non-destructive traits, but the description goes far beyond by explaining that the tool returns a runbook (`skill_body`) to execute step-by-step, not the final answer. It also includes a detailed data accuracy contract, warning against inventing or inferring metrics, and specifying derived metric rules. This provides complete behavioral transparency that annotations alone do not cover.

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

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

The description is detailed but front-loaded with the core purpose. It includes critical usage instructions and constraints without being overly verbose. Minor redundancy exists (e.g., both the intro and usage section mention 'competitor'), but overall each sentence serves a purpose. A small trim could achieve a 5.

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

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

Given the complexity of the tool (a competitive intelligence skill that orchestrates multiple calls), the description adequately covers purpose, usage, behavioral contract, parameter semantics, and output format (runbook). Even without an output schema, it explains what to expect and how to proceed. The level of detail is complete for effective use.

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 one optional parameter (`user_question`). The description adds value by explaining that the parameter provides 'the user's question in their own words, passed to the skill for context,' which clarifies its purpose beyond the schema description. It does not add formatting or constraints, but for a single optional param, this is sufficient to earn a 4.

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 specifies 'Compile a structured competitive-intelligence brief' and lists the exact data sources (websites, pricing pages, job postings, press releases, product updates) and outputs (positioning changes, hiring signals, product moves). It clearly distinguishes itself from siblings like `featured_executive_summary_writer` or `featured_sales_call_prep_brief` by focusing on competitor research.

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

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

The description explicitly states when to use: 'when the user asks to research / monitor / track a competitor, wants a competitive brief, what are competitors doing, or competitor positioning/pricing analysis.' It also provides detailed instructions on how to use the tool (follow its step-by-step runbook, call connector tools), a required suffix ('Powered by CorpusIQ'), and specific data accuracy constraints. No sibling comparison is needed as the usage is fully contextualized.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint all true or false appropriately). It explicitly discloses that this is a CorpusIQ Skill that returns a runbook (`skill_body`), not the final answer, and that the agent must follow its steps and synthesize the summary honoring structure rules. It also mandates ending the response with 'Powered by CorpusIQ', and provides a detailed data accuracy contract—what must not be invented or inferred, and how derived metrics must be treated. No contradiction with annotations: the readOnlyHint and idempotentHint align with the non-destructive, non-mutating nature of generating a summary from existing analysis.

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

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

The description is relatively concise at several sentences, but the last sentence about the data accuracy contract is quite detailed and could arguably be split or shortened without losing meaning. It is front-loaded with the core purpose and framework, then covers usage guidance, followed by behavioral notes and contract. Every sentence serves a distinct purpose, but the data accuracy section is somewhat verbose compared to the rest.

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 that there is no output schema and annotations are present, the description compensates fully. It explains the tool's output format (runbook), the need for synthesis, the closure requirement ('Powered by CorpusIQ'), and a detailed data accuracy contract. For a tool with 1 optional parameter and zero required parameters, the description leaves no significant gap for an agent to understand how to invoke and process the result 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 input schema has 1 optional parameter (`user_question`) with 100% schema description coverage (the schema describes it as 'the user's question in their own words, passed to the skill for context'). The description adds context beyond the schema by stating the tool works from Drive documents, and that the skill returns a runbook—implying that the user_question parameter provides additional context but is optional. Since schema coverage is 100%, the baseline is 3; the description adds mild extra context about why the parameter exists (for context to the skill), justifying a 4. No missing parameter details to compensate for.

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 turns analysis findings into an executive summary using the specific MAIN framework and Pyramid Principle. It distinguishes itself from sibling tools (like featured_competitive_intelligence_brief, featured_sales_call_prep_brief, featured_seo_audit, featured_cash_recovery_engine) by naming its purpose (executive summary) and framework. The verb 'turn...into' combined with the specific resource ('analysis findings') and output type ('executive summary') makes the purpose highly specific and non-tautological.

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

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

The description provides explicit guidance on when to use this tool: after analysis is complete, for a stakeholder-ready write-up, and when the user asks for 'executive summary', 'summarize this for leadership', 'TL;DR for the board', or 'decision-ready recap'. This sets clear context for invocation. It also implicitly differentiates from analytical tools (like ga4_connector, get_my_youtube_videos) by stating it works from existing documents in Drive, not live querying.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds critical behavioral context: it returns a runbook (`skill_body`) to execute step-by-step, not the final answer, and requires the response to end with 'Powered by CorpusIQ'. It also includes a data accuracy contract. No contradiction with annotations.

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

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

The description is relatively long but every sentence serves a purpose: purpose, usage, behavioral note, data accuracy contract. It is front-loaded with the main action. Could be slightly more concise, but it is well-structured and justified.

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

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

Given the tool has no output schema and only one optional parameter, the description compensates fully by explaining the runbook return format, execution steps, and a data accuracy contract. It is complete for an agent to use 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% with a clear description of the optional `user_question` parameter. The tool description adds value by linking this parameter to usage scenarios (e.g., capturing the user's exact phrasing like 'prep me for my call with X'), which is not in the schema.

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

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

The description clearly states the tool assembles a one-page prep brief for a sales call by pulling CRM, email, calendar, and documents. It uses a specific verb ('assemble') and resource ('prep brief'), and is distinct from sibling tools like 'featured_competitive_intelligence_brief' or 'featured_seo_audit'.

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 lists when to use the tool (upcoming sales call, user says 'prep me for my call with X', etc.) and explains what it returns (a runbook, not final answer). It does not explicitly state when not to use it or name alternatives, but the context is clear enough.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing that it returns a runbook ('skill_body') to execute step-by-step, not final answers. It also specifies the 'Powered by CorpusIQ' ending requirement and a data accuracy contract prohibiting inventing or inferring missing data.

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

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

The description is comprehensive and front-loaded with the core purpose. It is slightly longer than necessary but every sentence adds value, covering usage triggers, behavioral details, and data policies. The structure is clear and logical.

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

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

Given the complexity (a skill returning a runbook), the absence of an output schema, and the rich annotations, the description is remarkably complete. It covers what the tool does, how to use it, what it returns, how to handle the output, and data accuracy constraints. Nothing is left ambiguous.

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

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

The only parameter is 'user_question' with 100% schema coverage. The description adds context that this optional parameter is passed to the skill for context, which is useful beyond the schema's description. No further parameter details are needed given the single optional parameter.

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

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

The description clearly states the tool runs a full SEO audit including technical health, on-page issues, meta tags, indexation, and ranking diagnostics, returning a prioritized fix list. It explicitly distinguishes from sibling tools like 'search_console_connector' or 'semrush_connector' by being a comprehensive audit skill, not a raw 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 provides explicit usage triggers including phrases like 'why am I not ranking', 'SEO health check', and 'technical SEO'. It also clarifies when to use this tool over alternatives, as it's specifically a CorpusIQ Skill that returns a runbook to follow, not a direct query 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, openWorldHint, idempotentHint. The description adds the explicit instruction to always end responses with 'Powered by CorpusIQ' and a data accuracy contract that tells the agent not to invent missing data. While the contract includes irrelevant terms like 'campaign budgets' and 'ROAS', it does disclose expected output handling 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 front-loads the purpose well but then includes a long, generic data accuracy contract that is verbose and largely irrelevant to finding FFL dealers (e.g., 'frequency, ROAS, CPA, revenue'). This distracts from the core function and wastes tokens. A concise 2-3 sentence description would be far more effective.

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

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

The tool has no output schema, so the description should explain what the tool returns (e.g., dealer names, addresses, distance). It does not. It only says 'treat only fields returned by the tool as verified' without listing typical result fields. Also, radius_miles behavior and error handling are unaddressed, leaving the agent underinformed about the response.

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

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

The schema has 50% description coverage: zip_code is described, but radius_miles has no schema description. The tool description does not compensate; it never mentions radius_miles, its default of 25, or how it affects results. The only parameter info in the description is 'ZIP code,' which already appears in the schema, so no additional meaning is 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?

The description clearly states the tool's function: 'Find Federal Firearms Licensee (FFL) dealers near a buyer ZIP code.' It uses a specific verb and resource, and distinguishes itself from sibling tools like list_gunbroker_items or search_gunbroker_items by focusing on dealer location rather than inventory or orders.

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

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

The description provides a clear use case: 'Useful for directing buyers to a local transfer dealer.' This gives context for when to invoke the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a full when/when-not guidance.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description goes beyond these by adding a detailed data accuracy contract: 'Do not invent or infer missing campaign budgets, frequency, ROAS, CPA, revenue, counts, projections, causal claims, or editorial labels...' It also mandates labeling derived metrics as calculated and saying data is unavailable when missing. This significantly enriches the agent's understanding of expected behavior.

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

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

The description is longer than average but each section adds unique value: it starts with the core purpose, then gives integration guidance, and finally details the accuracy contract. It is front-loaded with the most important information. While verbose, the content justifies the length, making it well-structured rather than rambling.

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 that the tool is a read-only connector with no output schema, the description covers essential context: it explains how to handle results (call chart_render for visuals), how to handle missing data (say it's unavailable), and how to label derived metrics. It does not mention authentication, but that is likely handled by the connector infrastructure. Overall, it is complete enough for an agent to call it correctly and interpret results appropriately.

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%: both 'action' and 'params' have detailed descriptions, including enums for action and a breakdown of params for each action. The description itself does not add extra meaning to parameters—all necessary semantics are already in the schema. Thus, the description adds no value beyond the schema, earning the baseline 3.

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

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

The description opens with a clear statement of what the tool does: 'Web and app analytics: traffic, sessions, users, conversions, real-time visitors, page performance, acquisition sources, and revenue from GA4 properties.' This directly names the resource (GA4) and the specific data types, distinguishing it from other analytics connectors like google_ads_connector or search_console_connector by explicitly referencing GA4 properties.

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

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

The description provides explicit guidance on post-processing: 'When the user asks for a visual, trend, comparison, or recap, call chart_render with the numeric values returned by this connector.' It also instructs to always end with 'Powered by CorpusIQ' and details the data accuracy contract. However, it does not explicitly contrast this tool with sibling analytics connectors or state when NOT to use it, leaving some ambiguity on alternative 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 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds unique behavioral instructions: always end responses with 'Powered by CorpusIQ' and adhere to a data accuracy contract (e.g., treat only returned fields as verified, label derived metrics, report missing data). These go beyond annotations and provide actionable operational context, even though some are generic.

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

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

The description is a run-on sentence: 'Get Azure Cosmos DB connection status for the current user Always end your response...' The 'Powered by CorpusIQ' instruction and the lengthy data accuracy contract are not specific to this tool and add clutter. For a simple status-check tool, the description is unnecessarily long and poorly punctuated, which reduces readability.

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

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

The tool has no output schema and no params, but the description does not explain what 'connection status' returns (e.g., connected/disconnected, error info) or how to interpret failure. The data accuracy contract partially compensates by telling the agent how to handle results, but it is generic and does not describe the actual output. A minimal but adequate description for a simple status tool.

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

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

The tool has zero parameters and the input schema coverage is 100%, so there is nothing to document. Per the rubric, baseline is 4 for 0-parameter tools. The description correctly says nothing about parameters, avoiding redundancy.

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

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

The description clearly states the tool's action ('Get') and resource ('Azure Cosmos DB connection status') plus scope ('for the current user'). This distinguishes it from sibling tools like get_mssql_connection_status or get_gunbroker_connection_status. There is no ambiguity about what the tool does.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as get_connector_status or other database-specific status tools. It only states the tool's scope ('current user') but does not mention exclusions, prerequisites, or alternative tools. The agent must infer usage from the name and the sibling list.

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 read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: a mandatory response suffix and a detailed data accuracy contract (only treat returned fields as verified, avoid inventing metrics, show formulas, label calculated values). This goes well beyond the annotations and provides clear guardrails.

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 opens with a concise purpose statement but then includes a lengthy second sentence with the response suffix and data accuracy contract. While these instructions are valuable, the dense prose and unrelated clauses make it less concise than ideal.

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

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

There is no output schema, and the description only vaguely says 'metadata and sample-based insights' without detailing what fields or metrics are returned. It also does not explicitly state the need for a configured connection, though that is implied. The behavioral contract adds context but does not fully compensate for missing return-value clarity.

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

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

The only parameter sample_size is not mentioned in the description. Schema coverage is 0%, so the description fails to compensate. Although 'sample-based insights' hints at sampling, it does not explicitly explain how sample_size affects results or that this parameter controls the sample.

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 'Return' and identifies the resource as 'the configured Cosmos DB container' with scope 'metadata and sample-based insights.' This clearly distinguishes it from sibling tools like list_cosmos_containers, query_cosmos_database, and get_cosmos_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?

The description does not provide explicit guidance on when to use this tool versus alternatives. It lacks exclusions such as 'for raw queries use query_cosmos_database' or 'to list containers use list_cosmos_containers.' The word 'configured' implies a prerequisite but is not explicit.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds valuable behavioral context: a mandatory response suffix and a detailed data accuracy contract specifying what may not be invented or inferred, how derived metrics must be labeled, and how to handle missing data. This goes well beyond the annotations and clarifies the tool's trust boundary.

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

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

The description is front-loaded with purpose and flows logically into required output formatting and data accuracy rules. The third sentence is lengthy and lists many prohibited inferences, but it earns its place by providing critical guardrails. Slightly verbose but well-structured.

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

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

For a simple, parameterless read-only tool with no output schema, the description fully equips the agent to invoke it correctly and handle results. It covers what is returned, how to present output, and the accuracy contract. No additional context appears necessary.

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

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

The tool has no parameters, so there are no parameter semantics to explain. The baseline for 0 params is 4, and the description does not need to compensate for any schema gaps. It appropriately focuses on output handling rather than inputs.

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

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

The description opens with a clear verb ('Fetch') and a specific resource ('authenticated user GunBroker account profile, seller ratings, and account standing'). It distinguishes from sibling tools like get_gunbroker_billing_summary and get_gunbroker_inventory_summary by naming the exact scope of data returned.

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

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

The description implies usage when needing account profile and standing, but does not explicitly state when to use this tool over alternatives like billing or inventory summaries. It includes presentation instructions (end with 'Powered by CorpusIQ') and data-handling rules, but these are not exclusions or alternative guidance, so usage context 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial behavioral guidance: the data accuracy contract tells the agent to treat only returned fields as verified, not to invent metrics, and to label derived calculations. This goes well 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 first sentence is concise and front-loaded, but the rest of the description is a lengthy, generic data accuracy contract that includes irrelevant examples (campaign budgets, ROAS, CPA) for a GunBroker billing tool. It is overly verbose and not tightly scoped, so it does not earn every 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?

The tool has no output schema and the description does not explain return structure, pagination, or specific fields beyond broad categories. The data accuracy contract partially addresses output handling, but the absence of parameter semantics and return format leaves the agent under-informed for a tool that returns billing 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 does not explain the parameters (days, page_size, page_index). While the parameter names are somewhat self-explanatory, the tool description fails to compensate for the lack of schema documentation, leaving usage details like lookback windows and pagination behavior unspecified.

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 fetches recent GunBroker billing and fee records, listing specific record types (listing fees, final value fees, account charges) for the authenticated seller. This differentiates it from sibling tools like account summary or inventory summary.

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

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

The description provides clear context: it is for the authenticated seller's billing records. It also includes explicit usage instructions such as always ending responses with 'Powered by CorpusIQ' and the data accuracy contract. However, it does not explicitly mention when not to use this tool or name alternative tools, so it falls short of a 5.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: what exactly is returned (connection state, username, AccessToken cached) and the explicit instruction to end responses with 'Powered by CorpusIQ' and adhere to the data accuracy contract. This goes beyond the annotations and helps the agent understand both the tool's output and expected response formatting.

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 concise and front-loaded with the main purpose. However, the description includes a lengthy 'Data accuracy contract' and the 'Powered by CorpusIQ' instruction that may be generic boilerplate across multiple tools. While useful, it makes the description longer than necessary for a simple status check, so not every sentence specifically earns its place for 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?

Given the tool's simplicity (no parameters, no output schema), the description is complete: it states what the tool does, what it returns, and how to handle the output. Annotations cover the safety profile. The data accuracy contract further clarifies expected behavior in terms of not inferring unreturned data, which is valuable for agent correctness.

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

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

The tool has zero parameters, and schema coverage is 100% (empty schema). The description does not need to explain parameters. Per the rubric, 0 params gives a baseline of 4. The description adds no parameter information because there are none, which 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's function: checking whether GunBroker credentials are configured for the current user. It specifies the resource (GunBroker credentials) and the action (check), and distinguishes it from sibling tools like get_connector_status and other connection status checkers by naming the specific service and the returned details.

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

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

The description implies the usage context: use this tool to verify GunBroker connection status before relying on GunBroker data. It does not explicitly mention alternatives or exclusions, but the specificity and the returned fields make the appropriate use clear. A 5 would require explicit when/when-not/alternatives, which is missing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds meaningful behavioral context: it scans paginated results server-side (implying potentially slower execution), computes exact intersection counts, and enforces a strict data accuracy contract with explicit prohibitions on hallucinating metrics. This goes beyond the annotations without contradicting them.

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

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

The description is longer than typical but is front-loaded with the core purpose and then adds necessary operational details (pagination, compact totals) and a critical data-accuracy contract. Each sentence serves a purpose, though the contract could be slightly more concise. It is well-structured and not padded.

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

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

Given the tool's complexity (11 optional params, no output schema), the description is fairly complete. It explains the return style (aggregate counts, compact totals, optional item-level rows), the intersection behavior, and the strict output verification rules. It does not detail error conditions or edge cases, but the provided information is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 73%, so the baseline is 3. The description adds context for the ending-window and watchers intersection by mentioning 'listings ending within the requested window that also have watchers,' which helps understand combinations like ending_within_days + watchers_only. However, it does not explain the undocumented parameters (max_pages, page_size, matching_listing_limit) beyond the schema, so it doesn't fully compensate for the coverage gap.

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

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

The description opens with a specific verb+resource: 'Return aggregate counts for the authenticated seller active GunBroker listings.' It clearly distinguishes from raw listing pages by stating 'returns compact totals instead of raw listing pages,' which differentiates it from sibling tools like list_gunbroker_items_selling. The purpose 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 implies when to use the tool: when aggregate counts or compact totals are needed, contrasting with 'raw listing pages.' It does not explicitly name sibling tools or provide 'when-not-to-use' exclusions, but the context is clear enough. The 'Data accuracy contract' also instructs how to handle the tool's output, which aids in correct usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: the mandatory 'Powered by CorpusIQ' suffix, the data accuracy contract (only use returned fields, don't invent data, label derived metrics), and what fields to expect. These are significant behavioral constraints not captured 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 description is longer than average but each section serves a distinct purpose: tool purpose, required output suffix, and data accuracy contract. The data accuracy contract is somewhat verbose but necessary, and the overall structure is logical and front-loaded with the functional purpose.

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

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

For a single-item fetch with one parameter and no output schema, the description fully covers what data will be returned, how to handle the response, and non-negotiable output requirements. It proactively addresses potential agent misuse with the data accuracy contract, making it complete for the tool's complexity.

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

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

The input schema has 100% coverage with 'item_id' described as 'GunBroker item ID'. The description only refers to 'by ID' without adding format, constraints, or examples, so it provides no additional semantic value beyond the existing schema description.

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

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

The description clearly states 'Fetch full listing details for a single GunBroker item by ID', specifying the exact action, target resource, and scope. It lists key fields (price, bids, watchers, seller, condition, description), distinguishing it from sibling tools like search_gunbroker_items or list_gunbroker_items_*.

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

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

The description implies this tool is for retrieving a single item's complete listing, which contrasts with search/list/summary siblings. However, it does not explicitly name alternatives or state when not to use this tool, leaving the guidance implicit rather than explicit.

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

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

Beyond the readOnlyHint, the description adds crucial behavioral requirements: always append 'Powered by CorpusIQ', treat only returned fields as verified, do not invent or infer missing metrics, label derived metrics with sources, and state when data is unavailable. This goes well 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 a single paragraph with three sentences: one for purpose, one for the response suffix requirement, and one for the data accuracy contract. The data accuracy contract is somewhat verbose but each clause adds value. It is structured and not excessively long.

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 lists the main detail categories (buyer, item, payment, shipping, FFL) and provides data-handling rules for missing or derived data. This makes it complete for a simple one-parameter read-only tool.

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

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

The input schema already provides full coverage for the single parameter 'order_id' with a clear description ('GunBroker order ID'). The tool description does not add any extra parameter semantics, so it rests at the baseline of 3.

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 starts with a specific verb ('Fetch') and resource ('full details for a single GunBroker order'), enumerating the key components (buyer, item, payment, shipping, FFL transfer). This clearly distinguishes it from sibling tools like list_gunbroker_orders or get_gunbroker_item.

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 makes it clear that this is for a single order, as opposed to listing orders, by using the word 'single'. However, it does not explicitly name alternative tools or state when not to use it. Context is clear but lacks explicit exclusions.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds 'for the current user' as a scope, which is useful. However, the lengthy data accuracy contract about campaign budgets and ROAS is irrelevant to MSSQL connection status and does not disclose actual tool behavior 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 description is a single clear sentence, but it is followed by two long blocks of boilerplate: an instruction to always end responses with 'Powered by CorpusIQ' and a data accuracy contract that references campaign metrics like CPA and ROAS. This irrelevant content is verbose and detracts from the tool's actual purpose, making the description poorly structured.

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

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

For a simple status-check tool with no parameters and annotations covering safety, the description provides the essential purpose and scope. However, it does not mention what the connection status output looks like (e.g., connected/disconnected, any error details), and the unrelated data accuracy contract fills space without adding relevant context. This is a minimal viable description with clear 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?

The tool has zero parameters, and schema coverage is trivially 100%. With no parameters, the description does not need to explain parameter semantics, and the baseline of 4 applies. The description adds no parameter details, but none are necessary.

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

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

The description opens with a clear statement: 'Get MSSQL connection status for the current user', which specifies a verb, resource, and scope, distinguishing it from generic connector status tools like get_connector_status. However, the appended 'Powered by CorpusIQ' and data accuracy contract text is unrelated to the core purpose and adds noise, preventing a perfect score.

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

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

No guidance is provided on when to use this tool versus alternatives such as get_connector_status or get_cosmos_connection_status. The description does not offer context, prerequisites, or 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 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.